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INTRODUCTION 


What is PANEL Plus? 


PANEL Plus is an advanced screen design and management 
utility for use in program development. There are two parts to 
PANEL Plus: 


e Utility programs for easy, interactive design of screen 
layouts. | 


e Asubroutine library, with full source supplied, for 
manipulation of screens and fields. 


These two parts of PANEL Plus are designed to be used in 
conjunction: screen layouts created with the utility programs 
are stored in a format which can be used directly by functions 
in the subroutine library. 


PANEL Plus is a development of Roundhill’s ‘PANEL’ system 
and shares with it the same three major objectives: 


e Productivity in application development through 
interactive design of screen layouts and the ability to 
specify field processing at the time the screen is 
designed. 


e Portability of applications developed using PANEL 
Plus to the widest possible range of operating 
environments, without modifying application code. 


e Quality of user interface resulting from the built-in 
field editing functions, and features such as pop-up 
help boxes. 


This manual explains in detail how PANEL Plus meets these 
objectives and describes how to use the system to create your 
screen based applications. The reference chapters for the 
function library detail the syntax and operation of each function. 
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Some basic concepts 
Some basic concepts 


The main ‘object’ in PANEL Plus is the field. Virtually 
everything you display on a screen is a field. A field is defined 
by a field control block and consists of a rectangular area on the 
screen together with an associated data area (which may be 
larger than the visible screen area). The field control block 
also contains descriptive information about field display and 
entry attributes. 


It is important to realise that although PANEL Plus can appear 
to control ‘windows’, it is not a ‘windows’ system like packages 
such as curses. For output under curses, the programmer must 
first define a window and then render text into it using function 
calls similar to normal ‘console output’ calls. PANEL Plus 
operates in the opposite sequence: you place data for display 
into the field’s data area and then make a PANEL Plus call to 
display the field. Input functions exhibit similar differences: 
instead of a ‘console input’ operation in a curses window, 
PANEL Plus input is done by a ‘field read’ function, which 
delivers the data to the field’s data area, for use by your 
program. 


PANEL Plus fields can be displayed in two distinct ways under 
control of an application program. The ‘standard’ method is to 
simply output the field to the defined area of the field, 
overwriting whatever was there already. With the other 
method, known as ‘overlay mode’, PANEL Plus automatically 
saves the current contents of the defined screen area and then 
displays the field. This second method allows the field to be 
‘unshown’ at a later time by restoring the saved screen 
contents. You can choose the method to be used either 
explicitly when you display a field or group of fields, or at the 
time the field is defined. 


The highest level of PANEL Plus object is a collection of 
screen fields to be used in one part or phase of your 
application. This is known as a screen panel and is defined by a 
panel control block, which consists mainly of pointers to its 
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Portability issues 


constituent fields. The screen panel is the object created and 
edited by the panelp screen editor utility program. An 
application program can contain and use more than one screen 
panel. 


Screen panels created with the panelp editor can be 
incorporated in two ways into your application programs. In 
the first, the pangenc code generator is used to generate data 
definitions for the control blocks and data areas into a source 
module which is compiled and linked into your program. In 
the second method, the screen panel specification can be 
loaded by your program at run-time. The advantages and 
disadvantages of each method are discussed in a later section. 
A program can include both generated and dynamically loaded 
screen layouts 


Portability issues 


PANEL Plus includes full source code for the library functions, 
but not for the utility programs. This is because PANEL Plus 
libraries may be built into your developed applications without 
payment of royalties, but the PANEL Plus licence covers only a 
single development system. The provision of library source 
allows you to transport PANEL Plus libraries, with your 
applications, to environments other than that in which you 
develop your screen layouts. Please note that the standard 
PANEL Plus licence does not permit the distribution of our 
libraries in source, object, or library form. 


The PANEL Plus library was designed from the start for 
portability, and the source includes variants for a number of 
supported environments. A later section describes how to set 
about porting the library code. 


The other aspect of portability is the interfacing of different 
screens and keyboards. Here PANEL Plus gives you several 
methods of achieving portability with minimal change to 
application code. You can select the method by including 
different sets of low-level modules when linking your 
application: 
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Converting applications from PANEL 


e PANEL Plus has a built-in terminal interfacing system 
based on the tailor program, which maintains a 
database of terminal and keyboard capability. 


e modules are also provided to interface with an 
operating system’s own portability mechanism, if 
suitable. Examples are the UNIX termio database and 
the similar tcap under QNX. 


e PANEL Plus can be linked to operate with maximum 
performance on specific hardware. For the IBM 
Personal Computer and fully compatible systems a 
‘memory-mapped’ low-level module is provided, with a 
corresponding keyboard look-up table. 


e various graphics development systems are supported by 
special low-level modules which allow PANEL Plus 
application programs to operate in graphics mode. 
Generally the graphics package will handle device 
independence across screens of different resolution 
and colour capability. 


The selections for screen and keyboard interfacing can be 
made independently, so that for example you could combine a 
fixed keyboard table look-up with the use of termio for screen 
output. The source code for tailor is provided, so that you can 
use it to interface terminals in a new environment to which you 
port your application. 


Converting applications from PANEL 


If you already use PANEL and wish to convert applications to 
use the PANEL Plus library, you should read the special 
section later in this manual. We have provided almost all of 
the original PANEL calls in PANEL Plus, and the format of 
the disk files in which screen layouts are stored is upward 
compatible from PANEL to PANEL Plus. If you have changed 
our validation functions, however, you will need to change your 
present code slightly. 
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Organisation of this manual 


After making the necessary changes in any custom validation 
routines which you have written, there should be little problem 
in calling the PANEL Plus library from your existing 
applications. The use of the old-style calls may result in a 
slightly larger program than a similar one which uses only the 
PANEL Plus calls. 


One change you will notice is that all the PANEL Plus function 
names are now in lower case letters. To avoid having to edit 
existing programs we have provided a header file containing 
defines to change case, for use if your compiler and linker are 
case-sensitive. 


Organisation of this manual 


Chapters 1 to 11 of the manual are intended as a tutorial 
introduction to PANEL Plus, including explanations of how to 
use all of the PANEL Plus utilities and an overview of the 
PANEL Plus library. 


Chapters 12 to 20 are the library reference section. The last 
two of these chapters have a different style because they 
provide documentation about how to use library source code 
rather than how to use library functions. 


The remaining chapters explain how to use the PANEL Plus 
tailor system to make your programs portable to different 
screens and keyboards, and how to configure programs for 
those environments which are supported directly without using 
the tailor facilities. Chapter 25 includes specifics on 
conversion of existing programs written with PANEL to use the 
PANEL Plus library instead. 
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TECHNICAL SUPPORT 


On-line support for PANEL and PANEL Plus is available on 
McGraw Hill’s Byte Information Exchange (BIX) network. 
Roundhill Computer Systems operates a ‘vendor support’ 
conference where BIX users may post queries about PANEL 
and discuss techniques and applications with other PANEL and 
PANEL Plus users. 


Existing BIX subscribers 


If you already subscribe to BIX, join the roundhill conference. 
There are general topics for Panel and PANEL Plus, and 
specific topics for the PANEL versions for Basic and 

~ FORTRAN. For queries which you do not wish to post in the 
open conference you may send bixmail to the Roundhill 
conference moderator. 


We have arranged with BIX a 10% discount on your connect 
time charges while you are in the roundhill conference. 


New subscribers to BIX 


BIX is a dial-in conference system that covers 
computer-related topics such as hardware, software, languages, 
and general interest items. Roundhill is among several vendors 
who provide technical support conferences on the BIX 
network. A $10 discount on your initial BIX registration fee 1s 
offered to PANEL Plus users. 


To subscribe to BIX in the USA, call Tymnet on (800) 336 
0149 and ask for your local access point. Then dial into 
Tymnet and immediately type an a, then bix at the login 
prompt. When BIX asks for your name, you can enter new and 
full details of registration procedures and fees will be given. 
Registration and usage fees are billed to your Master Card or 
VISA account. 
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BIX access from outside the USA 


After you register on-line, you are immediately taken to the 
BIX learn conference and can start using the system right away. 
To reach the PANEL and PANEL Plus conference, enter join 
roundhill. 


You will be sent hard-copy registration information after you 
have registered on-line, which you have to sign and return to 
BIX. At this time you can use the special discount voucher 
enclosed in this manual which provides a $10 discount on your 
BIX registration fee. 


BIX access from outside the USA 


To access BIX from outside the USA, you need an account 
with your local PTT company. In the UK, call linkline 0800 
282852 for information about setting up a British Telecom 
Packet Switchstream (PSS) account. The network address for 
direct access to BIX is 310600157878. In the UK, this code 
should be entered as A9301600157878. You will start the BIX 
login procedure at the point where you respond bix, and then 
proceed as described above. 


Other support sources 


We can also offer technical support by telephone, and will 
respond to support requests by FAX, telex, and mail. The 
numbers appear at the front of this manual. Our major 
distributors also offer technical support on PANEL and 
PANEL Plus. 


Before calling for technical support, please ensure that you 
know the exact version number of PANEL or PANEL Plus 
which you are using, and the manufacturer and version 
number of your compiler. This information is almost always 
necessary to answer your question. 
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INSTALLATION 


Installing PANEL Plus programs and files 


PANEL Plus is available in a large number of versions for 
different operating system environments, so it is difficult to 
generalise about how to install the software. We strongly 
recommend a hard disk system to use PANEL Plus (and to do 
any program development) but you can of course use PANEL 
Plus on‘a diskette-only system. 


If you have a diskette-only system, first make copies of the 
distribution diskettes and place the originals in a safe place. 
How you make up work disks will depend on the diskette 
capacity and your usual methods of working. You should find 
that the panelp editor and the pangenc code generator fit ona 
diskette (together with their message files) and leave plenty of 
room for some screen layouts and generated code. After you 
have used these programs to create screens you can copy the 
generated code to the disks you usually use for compilations. 
The PANEL Plus header (.h) files and libraries will need to be 
moved to the disks you currently use for these file types. If you 
are using the PANEL Plus tailor program to configure 
applications for your screen and keyboard you will need the 
small PANEL.VDU file on each diskette. 


Most UNIX and XENIX versions of PANEL Plus are 
distributed in tar or cpio format: if this is not the case the 
distribution medium will so indicate. The first step is to unload 
the contents of the distribution medium into a temporary 
directory and change the file ownership and permissions to 
match installation standards. 


The distribution files should then be moved to appropriate 
subdirectories to correspond with your usual method of 
working. General guidelines are as follows: 
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Configuring for screen and keyboard 


e header files (.h) should be placed in the standard place 
used for your other include files. 


e subroutine libraries should be placed in the standard 
place used for your other libraries. If you only use one 
‘memory model’ or other type of library variant, you 
should select only the corresponding PANEL Plus 
library. 

e executable files should be placed in a directory which 
can be accessed through your standard PATH. 


e the message files (.msg) should be placed either in a 
‘panel’ subdirectory or in the same directory as the 
executable files. In either case an environment 
variable of MSG should be set to the pathname used, 
terminated by your path separator character. If you 
are installing a new version of PANEL Plus, or 
upgrading from PANEL, please ensure that there are 
no PANEL message files accessable from PANEL Plus 
programs, or vice versa. 


e the source and other remaining files should normally 
be left in a subdirectory named ‘panel’. For MS-DOS 
and some other versions of PANEL Plus the source is 
archived to save disk space. Be sure to use the 
supplied archive extract utility (which for MS-DOS is 
licenced from System Enhancement Associates). 

Some compiler source libraries are supplied with an 
archive utility which will almost certainly not work with 
the PANEL Plus source archives. 


If your operating system includes a ranlib program, you must 
run it on each panel subroutine library file after the file has 
reached its final resting place in your system. This prevents /d 
reporting date errors. 


Configuring for screen and keyboard 


Unless your system has only one type of hardware for screen 
and keyboard (e.g. Amiga) it is necessary to set up a means of 
interfacing both PANEL Plus utility programs, and your own 
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applications, with your screen and keyboard. For the panelp 
utility program there are two ways of doing this: 


e You can use a special version of the program, if 
available, which is pre-configured for your system (e.g. 
the panelpi program for memory-mapped operation on 
an IBM Personal Computer or compatible system, or 
the panelpt program which uses termio in certain 
PANEL Plus UNIX versions). 


e You can run the tailor program as described in a later 
chapter to select or set up configuration parameters for 
the screen or keyboard. 


If your version of PANEL Plus includes pre-configured 
programs (such as the memory-mapped versions for the IBM 
Personal Computer and compatible systems) we strongly 
recommend using these versions, at least when you use PANEL 
Plus for the first time. You can experiment with TAILOR and 
configuration of terminals and keyboards after you have got 
used to using PANEL Plus and explored its features. 


Your own application programs (and pantest, which you can 
recompile and relink) can normally be linked either to work 
through the tailor configuration parameters, or through a 
special low-level module which will interface directly with the 
hardware. Low-level screen modules are currently available for: 


e the standard PANEL Plus configuration file created 
with tailor. 


* memory-mapped operation on the IBM Personal 
Computer and compatible systems. 


e output through termio. 


e various third-party graphics libraries, allowing 
operation in graphics mode. 


e Amiga Intuition (graphics mode). 
Low-level keyboard modules are currently available for: 


e the standard PANEL Plus configuration file created 
with tailor, 
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e table-driven operation pre-configured for the IBM 
Personal Computer or for various other systems. 


e input through termio. 


The provision of source also allows you to adapt PANEL Plus 
low-level modules for operation in other environments, 
including use with other graphics libraries, and the table-driven 
versions of the keyboard modules can easily be modified for 
other fixed key function codes. 


The IBM Personal Computer versions of the low-level modules 
are described in a later chapter. Documentation for the 
graphics versions of the modules is on the disk with the 
corresponding source files. 


The keyboard utility program is provided to display the keytop 
legends recorded in the current configuration file which has 
been created with tailor. 


Environment variables 


Panel programs and library routines make the following use of 
environment variables: 


e VDU = is used to locate the PANEL.VDU information 
when using this PANEL Plus configuration file created 
by tailor. 


e MSG= defines either a fixed message file name or, if. 
a directory name, the directory to be used for message 
files. Message files are required by panelp, tailor and 
pangenc. 


e PNL= is used by panelp, pantest, and pangenc to 
specify a directory for screen layout files. 

e TERM = is a terminal name used to look up 
PANEL.VDU information in TAILOR.DAT, and also 
by the PANEL Plus low-level module supporting 
UNIX termio. 

e TAILOR= is used as full path name to find 
TAILOR.DAT when TERM = is used. 
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e PNLMONO = if non-null, is used to force selection of 
monochrome attributes when using the PANEL Plus 
memory-mapped version for the IBM Personal 
Computer, for example when using a machine with a 
CGA-compatible monochrome display. 


e PAIATT= and PAIBOR= are used to specify 
hexadecimal strings of characters to define attributes 
and borders in some PANEL Plus versions. ‘The 
syntax for these variables is a string consisting of an 
even number of hexadecimal digits, which are used in 
pairs to initialise the corresponding array. 


The PANEL Plus convention for path names in environment 
specifiers is as follows: if the environment variable value ends 
with the path separator character, it is taken to be a directory 
name to which the standard filename is appended, and if not, it 
is taken to be a complete filename. 


In systems which do not support an environment, processing 
proceeds as if the environment variables were not defined. 
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This chapter is intended to give a full description of how to 
write an application program using PANEL Plus, but without 
giving keystroke-by-keystroke instructions about how to carry 
out each operation. Later sections about each topic will fill in 
the details of each stage. 


Creating a screen panel layout 


The panelp program is used to set up a screen layout. Each 
screen panel layout is initially stored in a separate file with 
filename ending in ‘.PNL’ or ‘.pnl’ depending on your 
operating system conventions. (When your application 
development nears completion, those screen layouts which are 
to be dynamically loaded can be merged into a single data file). 


Each field has a ‘level number’ which need only be assigned as 
a non zero value if you wish to have overlapping fields in the 
panel. The only restriction on positioning fields is that fields 
with the same level number cannot overlap. 


Each area of the screen which is to be used to display or enter 
data must be defined as a field. This includes all of the 
‘prompts’ which you may think of as a background to your data 
entry fields. You can in fact define one field the full size of the 
screen and enter all these background prompts or labels on it, 
using another ‘level’ for your data entry fields. But this may 
involve storing a data area in your program with large areas of 
blank space, and it takes longer to display it. We therefore 
recommend using separate fields for each of the text areas on 
your ‘background’ screen. This technique also makes program 
maintenance easier, since fields can be easily moved around 
the screen using panelp. The text entered in prompt or label 
fields is known as the field ‘initialisation’. Unlike a ‘default 
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value’ in an entry field, initialisation data is not remembered if 
your program overwrites it. 


Level numbers can be used to group fields in any way required 
by your application. It is generally preferable to define 
separate screen panel layouts for separate ‘entry forms’ rather 
than to create more and more levels in a single panel. Once 
again, your program is easier to maintain, and will probably be 
much more efficient. This is because the display routine © 
usually has to scan through all the fields of a panel to look for 
the fields on a specified level to display. If the fields for each 
entry form are included among several hundred other fields of 
a panel they will take much longer to find. 


As the screen layout is saved by panelp you can specify the 
sequence in which the fields are to be processed. The two 
standard sequences are from top to bottom of the screen and 
from left to right of the screen, but you can specify override 
sequence numbers for selected fields if you wish. 


Setting field attributes 


The panelp program is used to assign display and entry 
attributes to each field. The display attributes include such 
things as inverse video and field colour, as well as whether the 
field is surrounded with a ‘border’. There are three methods of 
specifying entry attributes for a field: 

e built-in attributes 

e character and line validation codes 

e extended field attributes 
The built-in attributes are, as indicated by their name, built in 
to the PANEL Plus field read functions. They include such 
items as whether a field has to be terminated or whether entry 
can be completed by filling it, and whether a field has to have a 
non-null entry (mandatory field). The effect of these attributes 
can only be modified by changing some of the PANEL Plus 
field primitive functions in the supplied source code. 
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The character and line validation codes are used to select one 
of the predefined special validation functions via a table of 
function pointers. The provided functions are each coded in a 
separate small module and can easily be changed, removed or 
replaced by custom validation for a specific application. This 
validation can then be selected for a field at the time the 
screen is designed. 


The extended field attributes normally operate in conjunction 
with one of the character or line validation functions. The 
extended attributes are stored in an area of up to about 1500 
bytes associated with each field, and can contain lists of valid 
field values, help messages, default values, numeric range 
check information, and anything else you may wish to add for 
your own applications. | 


The definition of field attributes is the main task to be carried 
out during the creation of a screen panel layout with panelp. It 
can be made easier by techniques such as copying each field 
from a field with similar attributes instead of starting afresh 
each time. Each data entry field should also be assigned a 
name which is carried into the generated code so that your 
program can refer to the field control block and the data area 
by name. 


Code generation or dynamic load? 


It is necessary to decide for each screen panel layout whether it 
will be built into your application as a compiled module or 
loaded at run time. 


The main difference as far as coding your application is 
concerned is that the field names are only directly available 
when you have compiled the generated module. For a loaded 
screen layout you have to refer to fields by number. And with 
a loaded screen layout each field’s data has to be referenced 
through a pointer in the field control block. For a compiled 
module, a field to which you have given the name fname has a 
field control block structure called fFNAME and a character 
array for its data named FNAME. 
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To make it easier to refer to field numbers in dynamically 
,;oaded screens, we provide utility programs enum and define 
which generate source statements of the corresponding type to 
associate field names with numbers. There is also a library 
function (pscana) which will scan through the field names in 
the field control blocks of a dynamically loaded panel and 
return the appropriate field number corresponding to the 
supplied name. But you will still find it somewhat less 
convenient not to have the control blocks and the data area 
names and sizes known to the compiler. 


Another important difference is that generated and compiled 
screen layout details are stored as static data, whereas loaded 
details are stored on the heap. A shortage or abundance of 
either type of memory in your application may therefore 
influence your choice. 


As far as possible, you should choose to generate code and 
compile your screen details if: 


e all other things are equal, 


e your application is likely to be subject to modification 
during its lifetime, especially if fields may be added 
and deleted, 


e your screen has a large number of input fields which 
you would like to be able to refer to by name. 
You should choose to load screen layouts dynamically at run 
time if: 
e your compiler imposes a limit on total static data 
storage which is causing you a problem, 
e your compiler cannot accept string literals of the 
length required for your help boxes or other extended 
attributes, 


e the screen is one which has few input fields (e.g. a full 
screen menu with one response field), 
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e the application has a large number of screens which 
are only required infrequently (e.g. full-screen help 
information), or 


e you wish to guarantee that all data areas for a screen 
are in a contiguous block of memory. 


There is no difference in the call syntax for PANEL Plus 
display and read functions between compiled and dynamically 
loaded screens or fields. 


Code generation 


The pangenc program generates C code consisting of data 
structures for field data areas, field control blocks, and 
extended attributes. Normally, no executable code is 
generated, but it is possible to specify the generation of a 
dummy procedure which may help you to manage program 
overlays in some environments. 


A large number of program options configure the code 
generator to cater for compiler idiosyncracies. You need to 
take special care when generating code on one system for use 
with a version of the PANEL Plus library you have ported to 
another environment. Although the .PNL files are designed to 
be completely portable, the generated code is in general not. 


The code generator creates two files for each panel. The first 
is a .C file which is compiled and linked with your application 
code. The other file is a .H file containing extern definitions 
for the data area and field control block of each field which 
you have assigned a name to. It is assumed that if you failed to 
assign a name to a field you do not want to refer to it explicitly 
in your application. 


Another utility, document, is provided to document a panel in 
the form of a list of field names, sizes and attributes. The 
source is available in case you need to enhance this 
documentation or add your own project headings. 
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An application program using the PANEL Plus library will 
usually contain as a minimum the following elements: 


e Initialisation function calls which allow PANEL Plus to 
determine on what screen and keyboard it is operating 
and to set up processing. 


e Preparation of display fields, including formatting of 
numeric values and determining defaults. 


e Display of fields and groups of fields. 


e Reading of information keyed into fields, with operator 
editing of entries and validation of data entered. 


e Utility functions such as those which clear the screen or 
manipulate field data areas. 


e Termination of processing, usually involving resetting 
the screen to default state. 


PANEL Plus functions are provided for each of these program 
elements. 


Writing programs in graphics mode 


All PANEL Plus text display, entry, and data validation 
operations can be performed with your screen in graphics 
mode using one of the supported third-party graphics library 
products. This feature allows graphics applications to have 
access to the powerful PANEL Plus data entry facilities, for 
example to pop-up a data entry window on top of graphics 
output. 


To use graphics mode you simply link your program with the 
alternate low-level output modules provided for each 
supported graphics library. We recommend that you use the 
normal PANEL Plus initialisation and termination functions to 
set graphics mode at the start of your program and to return to 
normal mode at the end. PANEL Plus field display and read 
operations may then be intermixed with direct calls to the 
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graphics library to display graphics output from your 
application. 


If you need to write your own code to start up graphics mode 
you may have to modify the supplied low-level interface 
modules to eliminate some of the initialisation operations; and 
select a mode compatible with the PANEL Plus graphics 
operations. Currently PANEL Plus only supports fixed width 
character fonts aligned at whole character boundaries. 
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This chapter describes the way in which your users will use 
your application. You may wish to adapt some of the text to 
incorporate in user manuals for your programs. 


In designing the PANEL Plus user interface, the two main 
principles have been simplicity and consistency. The first 
impression that the user should get from the sight of the screen 
layout is a framework into which data can be entered and an 
immediate indication of how to enter the data. PANEL Plus 
achieves this by encouraging the use of messages to the user 
which will appear at a constant, familiar, screen location, and 
by providing a software-controlled ‘screen protect’ facility 
which restricts input to the defined areas. By reading the data 
field by field, your program can also give immediate indication 
of errors. 


The appearance of a text data entry screen and the user editing 
features, remain consistent over all PANEL Plus versions, even 
when the application is running in graphics mode. Some 
versions allow a mouse button or other pointing device to be 
used to select an entry point. 


The actual process of data entry is made easier by the inclusion 
of extensive data editing and control features: 


e Cursor left and right functions permit non-destructive 
movement in the field, so that the operator can go 
back and correct a character without retyping the 
whole entry. 


e The destructive backspace function operates in the 
same way as for command entries and clears the entry 
backspaced over. In a field initialised with fill 
characters, the fill character can be used to replace the 
deleted character. 
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e Acharacter can be deleted, closing up the characters 
to the right. 


e The ‘insert character’ key can be used to insert a blank 
character under the cursor, with movement of the 
remainder of the field to the right. Alternatively the 
key can be set up to toggle ‘insert mode’ in which 
characters are shifted right as entry proceeds. 


e A field line can be erased from the cursor position. 


e Lines can be inserted or deleted in multiple-line fields. 
Cursor up and down functions are supported, and 
cursor wraparound occurs within the field in both 
directions. 


e The TAB function moves along the field word by word. 


e The use of the escape or ‘program function’ keys, and 
cursor movement out of the field, are reported to the 
application program to allow the appropriate action to 
be taken. 


e A question mark or other ‘help’ key can be used to 
provide special ‘help’ information for the field. 


Keyboard functions 


Because the PANEL Plus system allows so much flexibility in 
application design, particularly through the validation exits 
provided by the system, it is impossible to give hard and fast 
rules about the user interface and the operation of keyboard 
functions. 


As an example, the ‘carriage return’ function is normally used 
on entry either to move from one line to another inside a field 
or to move from one field to the next. Using the exit provided 
at the end of field entry, your application program can arrange 
that ‘carriage return’ terminates the entry of a complete screen, 
so that the arrow keys have to be used to move from field to 
field when the field is not completely filled. This feature can 
be used if end-users are already familiar with this style of 
operation as a result of using other applications. 
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The following descriptions of keyboard functions assume that 
the ‘default’ function assignments have been used in your 
application. 


Carriage Return This function will move the cursor to 
the start of the next line during entry into a multi-line 
field, or to the next field in sequence when on the last 
or only line of the field. 


Escape The escape function causes an immediate exit 
from field entry, and will normally be assigned by the 
programmer to return to the previous application 
function. 


Destructive Backspace This function will backspace the 
cursor, erasing the entry backspaced over. The erasing 
character will either be a blank space or the defined 
fill character, the latter being chosen when there is 
already a fill character at the current cursor position. 
The function is ignored in the first position of a field. 
When ‘insert mode’ is active, the characters to the 
right of the cursor are also dragged to the left. 


Cursor Left The cursor is moved to the left non 
destructively. At the start of a line, the cursor moves 
to the end of the previous line in a multi-line field, or 
to the previous field in sequence from the first or only 
line of a field. 


Cursor Right The cursor moves to the right non 
destructively. The character already in the new 
position in the field is accepted without validation. At 
the end of a line the line entry is only terminated if the 
‘CR Required’ attribute is off. 


Cursor Up Ina multi-line field, the cursor moves up to 
the same position on the line above, if present. On the 
first or only line of the field, the entry is terminated 
and the cursor returns to the start of the previous field 
in sequence. 


Cursor Down In a multi-line field, the cursor moves 
down to the same position on the line below, if 
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present. On the last or only line of the field, the entry 
is terminated and the cursor moves to the start of the 
next field in sequence. 


e Erase Line The line is erased from the cursor position 
to the end of the line, with all characters replaced with 
the defined fill character for the field. 


e Insert Character By default, a blank is inserted at the 
position of the cursor, and all characters on the line to 
the right of the cursor move to the right. Your 
program can also be set up to enable this key to toggle 
‘insert mode’ in which all characters to the right of the 
cursor move to the right. The rightmost character on 
the line is lost. This function is suppressed in a field 
for which an entry mask has been defined. 


e Delete Character The character at the cursor position 
is deleted, and all characters on the line to the right of 
the cursor are moved left one position. The defined 
fill character for the field is placed at the right-hand 
end of the line. This function is suppressed in a field 
for which an entry mask has been defined. 


e Insert Line Provided the cursor is at the start of a line, 
that line and all following lines of the field are moved 
downwards and a blank line is inserted at the cursor. 
The last line of the field is lost. This function is 
suppressed in a field for which an entry mask has been 
defined. 


« Delete Line Provided the cursor is at the start of a 
line, that line is deleted and all following lines of the 
field are moved upwards. A blank line is inserted at 
the cursor. This function is suppressed in a field for 
which an entry mask has been defined. 


e Tabulate The tab function will skip to the next ‘word’ 
in an entry field, which is defined as a non-blank 
character following a blank character. After the start 
of the last ‘word’, the cursor moves to the position 
following it, if available. In a field for which an entry 
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mask has been defined, it moves to the next block of 
‘entry’ characters. If there is no position in the field to 
move to as defined above, the cursor moves to the 
start of the next line in a multi-line field, or to the next 
field in sequence from the last or only line of a field. 

e Query The query function is highly application 
dependent. If a ‘help message’ or ‘help box’ has been 
defined for the field, that is displayed until the next 
character is keyed. Otherwise, in the first position of a 
field line the key causes an immediate exit from field 
entry with a special code returned to the program; 
elsewhere in a field a question mark is displayed in the 
field. An alternative mode can be specified for field 
read operations in which the help message is displayed 
throughout entry of a field and the help box only is 
displayed when the key is depressed. 


e Home The home key operates on one of three levels. 
First it will return the cursor to the start of the current 
line. If already there, the cursor moves to the start of 
the field. And if it already at the start of a field, it will 
normally move to the first entry field on the screen. 


e Program Function Keys Again, the action is application 
dependent. The first PF key, PF1. normally skips to 
the next field during multiple-field read operations, 
and any other PF key terminates the entire read 
operation. The PF1 key can therefore be used 
conveniently in a field with a large data area to avoid 
the need to scroll down to the bottom of the field. 


Mouse functions 


Some versions of PANEL Plus allow a mouse button to be 
used for cursor positioning. Normally, only the left button 1s 
used on a mouse which has multiple buttons. The action which 
takes place on pressing the mouse button is application- 
dependent, but usually the mouse can be used to reposition the 
cursor in a field or to select a different field during a 
multiple-field read operation. 
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You cannot move the entry cursor with a mouse button 
depression to a position outside a field or to an invalid position 
in a field (e.g. a non-entry position in a mask field). You also 
cannot move to a new field when there is a partial invalid entry 
in the current field. 


The mouse can also be used to select an item when the pmenu 
function is used. 


In PANEL Plus versions which support a mouse, the panelp 
and pantest programs also allow its use to select an item from 
the message line, by pointing to a letter in the list separated by 
‘’? characters at the end of the line. For IBM Personal 
Computer versions, only the panelpi and pantesti programs 
support this feature. 
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The standard validation routines described below are all 
provided in source code form as well as in the PANEL Plus 
library. The descriptions in this chapter outline the functions 
as provided, but obviously they will behave differently if you 
modify them to suit your application. 


In many cases the character and line validation codes interact 
with specific ‘extended attributes’. In such cases you need to 
specify both items correctly to implement the required 
validation for the field. The character validation number is 
usually used to select the ‘key validation’ function also, because 
both types work in conjunction. 


‘Extended attributes’ provide a powerful and flexible means of 
defining entry and display parameters. Up to sixteen types of 
extended attribute may be defined, but not all of these are 
currently in use in the PANEL Plus library. New types may be 
added by the application developer to meet specific validation 
requirements. 


Each extended attribute consists of a string of characters which 
has no inherent format. Some of the extended attribute types 
consist of sets of substrings which may be delimited by any 
character which does not appear in the substring. The 
delimiter character must immediately follow the two code 
letters and, most importantly must also appear at the end of the 
string. The source code in pxa.c must be modified slightly if 
you wish to use more than 32 substrings. If a screen layout is 
to be used with the PANEL version for FORTRAN, extended 
attribute substring delimiters are limited to ‘\’ and //. 


Built-in validation functions 


The built-in validation functions are in general implemented 
within the PANEL Plus field primitive functions, and so are 
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slightly less easy to change than those in external functions. 
They include the following: 


e The ‘U’ (upper case) attribute converts field input to 
upper case as it is entered. The default list for upper 
case conversion is ‘a’..‘z’, but an array of additional 
character pairs in paxtra allows accented characters in 
languages other than English to be added to the list of 


convertable characters. 


e The ‘E’ (echo) attribute causes input to be echoed as it 
is keyed. Its absence does not prevent the field 
contents from being displayed. 


e The ‘C’ (CR required) attribute requires a carriage 
return to be entered to complete a field line. Without 
it the line input will be considered complete as soon as 
the last character has been keyed on the line (i.e. when 
the line is full). 


e The ‘W’ (wipe) attribute has the effect of clearing the 
field as soon as the first data character is entered. You 
can use the right-arrow and tab keys to move into the 
field for editing, bypassing the “W’ attribute setting. 


e The ‘R’ (right-justify) attribute causes an entry to be 
redisplayed right-justified when the line is completed. 
The functions which move string data into a field data 
area also take note of this attribute when formatting 
the line. 


e The ‘I’ (integer) attribute validates and reformats the 
entry as a numeric value when the line entry is 
complete. The default is to allow a number to be 
entered with a decimal point and then to display the 
integer part only. Whether the item is rounded or 
truncated is dependent on the compiler library sscanf 
implementation. Changing the pavin array to omit the 
decimal point will limit entry to integer values. The 
NF extended attribute described below also affects this 
function. 
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e The ‘$’ (currency) attribute operates in a similar way 
but reformats the number with two decimal places. 
The format can be overridden using the NF extended 
attribute described below. The PANEL Plus libraries 
are created using a function whichimplements | 
currency values as pennies (or cents) stored as long 
integers, and formats them as pounds (or dollars) with 
two decimal places. The numeric validation function 
can be recompiled with a different define set to use 
double values instead. The supplied version limits 
currency values to 21,474,836.47 if long is 32 bits. 


e The ‘B’ (border) attribute specifies that the field is to 
have a ‘border’. The format of the border is defined 
by the BD extended attribute. 


e The ‘M’ (mandatory) attribute specifies that the field is 
to be a mandatory field. There are two types of such 
field: an ‘M’ attribute alone requires at least one 
character in the field not equal to the field fill 
character. When ‘M’ and ‘X’ are specified together 
the field must contain no instances of the fill character. 


e The ‘X’ (user-specified) attribute is generally available 
for use in application programs, but has also been 
stolen as a modifier for certain other attributes. For 
mandatory fields its effect is described above. For 
numeric fields it formats a zero value as an empty field 
instead of as a numeric zero value. And it also allows 
blank ‘date’ fields as valid. 


The built-in validation codes may of course be used in 
combination as required. Specifying ‘integer’ when the field is 
also ‘currency’ is a waste of a keystroke. 


Character validation 00 


The default character validation function does little except try 
to ensure that the character keyed is displayable. It does this 
by reference to the patdsp function in the active low-level 
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screen module. For numeric integer or currency fields, input is 
restricted to valid numeric characters. 


Character validation 01 


Instead of allowing all displayable characters to be entered, this 
routine restricts them to a user-specified subset. In the 
supplied programs, this subset is initialised to the letters 
‘A’.”Z’, but it can be changed by using extended attribute CL 
or by modifying the paval character array. 


Character validation 02 


Useful for*password fields, this routine displays any entered 
character as an ‘*’, while saving the true entered value in the 
field. Character validation 02 also affects the display function, 
and causes any existing contents of the field data area to be 
replaced with asterisks. 


Character validation 03 


This uses the ‘picture’ defined by extended attribute PV to 
specify validation separately for each character of the field. 


Character validation 04 


This function restricts the field entries to the digits ‘0’..’9’, 
without validating the whole line as a ‘number’. It is useful for 
fields such as telephone numbers and dates which may need to 
be entered under a mask. 


Character validation 05 


This function displays either ‘Yes’ or ‘No’ (provided the field is 
large enough) when either ‘Y’ or ‘N’ is entered. Other entries 
are rejected. If you have specified ‘CR required’ for the field, 
you will have the opportunity to backspace to the start of the 
field and re-enter the value; if not, a single keyed valid 
character will complete the field. Function key usage is 
restricted, and you cannot leave the field without selecting one 
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of the valid options. The emitted strings can be changed fro 
‘Yes’ and ‘No’ by specifying extended attribute VL. | 


Character validation 06 


For those data entry operators who are used to a typewriter 
keyboard, this routine allows entered values of *<’ and ">’ to 
be converted to comma and full stop (period) respectively. 
These special characters are often found on the ‘upper shift’ 
position of those keys, and many punctuation errors can be 
avoided. 


Character validation 07 


This validation routine implements a simple but effective 
word-wrap mechanism for data entry. It allows continuous 
keying into a multi line field, and if no space character falls at 
the end or the start of a line it will move an incomplete word 
from the end of one line to the start of the next. 


The routine does not support dynamic reformatting of the field 
when editing already displayed data. If you have to edit the 
start of a line which has a completely filled immediate 
predecessor line, a space character (which will be thrown away) 
should be entered first to inhibit word-wrap. 


Character validation 08 


This routine uses the associated VL extended attribute to step 
through a list of values when a single key is pressed. This 
routine is described in greater detail below. 


Line validation 00 


This routine implements the standard processing for numeric 
and currency fields. This fact is significant in that these 
numeric functions will not be performed when a non-zero line 
validation number is specified. 
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This routine checks that the value entered is one of the values 
specified in extended attribute VL. 


Line validation 11 


This routine validates a date entry in the format ‘DD/MM/YY’. 
Any non-numeric delimiters are accepted, but there must be 
two delimiters and three values in the field. If the field size 
allows, the year may be entered with more than two digits and 
is checked modulo 100, i.e. the ‘century’ is ignored. If the 
‘user’ attribute (X) is applied to the field, this routine treats as 
valid a ‘blank’ field containing only fill characters in entry 
positions 


Line validation 12 


Dates are checked in the same way as for function 11, but the 
input format caters for those countries where ‘month’ comes 
before ‘day’ MM/DD/YY’). 


Line validation 13 


Date validation as for 11 and 12 above, but format 
“YY/MM/DD’. 


HM Extended attribute — Help Message 


Normally, the help message text is displayed on the current 
message line whenever the defined help key is depressed 
anywhere in the field. The message is removed as soon as 
another key is depressed. An option on the pafr field read 
functions causes the help message to be displayed continuously 
as each field is read. 


CL Extended attribute — Character List 


The attribute string is used as a convenient means of overriding 
the paval string containing the valid characters for the field. It 
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PV Extended attribute — Picture Validation 


is therefore only effective when Character Validation number 1 
has been specified for the field. 


PV Extended attribute — Picture Validation 


This attribute string allows different validation to be specified 
for each field character by special codes which form a ‘picture’ 
of the field. The sample routine uses the picture characters ‘9’, 
‘a’, ‘A’, and ‘X’ only, but it is easy to add to or modify the 
processing so that, for example, upper case conversion is 
selected for certain positions only. Character Validation 
number 3 must be specified. 


VL Extended attribute — Values List 


The values list is used for three different types of field line 
operations, controlled by the character and line validation 
numbers: 


e Line validation number 2 checks the entered data 
against the substring list and rejects the field line if no 
matching entry is found. If a substring is shorter than 
the field length the excess in the field must be all fill 
characters to ensure a match. 


e Line validation number 5 uses the list to override the 
default ‘Yes’ and ‘No’ strings which are emitted when 
the first character of the field is typed. You should 
ensure that each substring begins with a different 
capital letter, or you may never see it emitted. 


e Character validation number 8 enables the operator to 
scan through a set of predefined values until the 
correct value is displayed. As coded, a space or plus 
sign moves forwards through the list, and a minus 
moves backwards. A null entry in the list allows 
normal data entry by the operator. The first substring 
is a dummy value consisting of a single upper-case 
letter indicating the element to select for initial display 
- ‘A’ for the first, ‘B’ for the second, etc. The pafp 
routine called to prepare the field for display will 
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either display the string corresponding to the letter or, 
if the field already contains data, will set the code 
letter (if possible) to match the displayed data. 


BD Extended attribute — Field Border 


The panel display routines can display a ‘box’ as a border 
surrounding the field. Border processing only takes place when 
the ‘B’ attribute is specified for the field. The field is then 
displayed with the default or alternate border according to the 
display function used. The BD extended attribute string is used 
to override the default border settings. In graphics mode, the 
border may be rendered using line-draw functions, and the 
extended attribute string may have different effects which are 
documented for the specific graphics environment. 


The default and alternate border characteristics are defined in 
the low-level screen module. When using PANEL.VDU, as set 
up by tailor, the first highlighting type found with a method 
code of 8 should have a special ‘on’ sequence to define the 
default border and a special ‘off sequence to define the 
alternate border. Each sequence consists of eight characters as 
follows: 


e The first two characters define a highlighting type and 
method if such is required to display the graphics 
characters. When specified, the border highlighting for 
a specific field border cannot override these values, 
which always take precedence. The two characters 
should be zero if a special ‘graphics mode’ is not 
required. 


e The next six characters define respectively the top left, 
top right, bottom left, bottom right, horizontal, and 
vertical characters. If fewer than six characters are 
specified, the last character is propagated to the right. 


If no highlighting type with method code 8 is found, or the 
selected sequence is not defined, the ‘box’ defaults to all ‘+’ 
characters. 
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The box definition for an individual field can be overridden by 
using the BD extended attribute. The extended attribute string 
consists of up to six substrings delimited by any character. ‘The 
delimiter character must start and finish the string. The first 
two substrings are numeric values to define the highlight type 
and modifier for the border. If not specified, these default to 
the same values as the field highlighting. The third substring is 
up to six characters defining the border as described above. If 
this third substring consists of the single letter ‘A’, the alternate 
border is selected. The fourth substring is an optional ‘legend’ 
which is placed in the top edge of the border. The fifth and 
sixth substrings are numeric values to define the highlight type 
and modifier for the legend. If not specified these default to 
the same values as the border highlighting. 


A negative value for the border highlight type in the first 
substring results in the display of the field being inhibited: only 
the border is displayed. 


The field border is not taken into account when determining 
the start position or size of the field with the field control block 
parameters: the border therefore lies ‘outside’ the field. When 
a field abuts an edge of the screen the whole of any defined 
border is suppressed. 


When defining ‘bordered’ fields with the panelp screen editor, 
you can overlay a corner of another field with the border 
characters, even if the fields are defined at the same ‘level’. If 
you subsequently move the ‘bordered’ field away, the overlaid 
corner may not be redisplayed automatically. To reshow the 
screen correctly, display a help screen and then return to 
redisplay the screen layout. 


NF Extended attribute — Numeric Field 


The NF extended attribute is used to specify additional 
operations on numeric fields, and to arrange for the data to be 
returned to your application as a numeric value. 
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The extended attribute string is divided up into substrings using 
any convenient delimiter. The first substring, if non-zero, is the 
array index into an array of numeric values. There are two 
arrays, panuml for integer fields and panumd for currency 
fields, These arrays are defined as Jong and DOLLAR 
respectively, where DOLLAR is defined as either long or 
double as required. 


If the default option (Jong) is chosen the display format 
assumes that the value is in cents (pennies) and field is 
displayed in dollars (pounds) with two decimal places. The 
display format cannot then be overridden. 


When DOLLAR is defined as double the field is also displayed 
with two decimal places by default, but the format can be 
overridden as described below. 


When pafp is used to prepare a numeric field for display, the 
value in the array element specified by the first NF extended 
attribute substring is formatted into the field. The result of a 
field read is also placed into the same array element. 


The second and third substrings, if not absent or empty, specify 
the low and high values for a field range check. This validation 
is carried out when the field is read. 


The fourth substring is only used with the PANEL Plus C 
interfaces. It is a printf format specifier which is used to 
override the default format. This provides an easy method of, 
for example, selecting a different number of decimal places for 
a value. Note that it may be possible to crash your program 
with a bad choice of format specifier. 


NEF/1/ - use array element 1 
NF/3/0/999/ - use array element 3, test for 
positive less than 1000 
NF//0/ - test for positive 
NF////%-1.4f/ - display with 4 decimal places 


Examples: 


The fifth and sixth substrings are only for the PANEL 
MS-FORTRAN interface. The fifth substring defines for 
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integer fields the minimum number of digits to be shown. For 
example a value of 3 will format a ‘one’ as ‘001’. For real fields 
it specifies the number of decimal places. 


The sixth substring can be entered as an ‘E’ (upper or lower 
case) to force the use of the ‘E’ format for display. Normally 
the ‘E’ format is used only if the field is too small for the 
number of significant digits in the value. The ‘E’ format is 
accepted for input of data to a real (‘currency’) field. Note that 
the exponent is shown by default with two digits, unless the 
FORTRAN numeric validation module is recompiled. 


HB Extended attribute — Help Box 


Similar to the help message, the message specified in the 
extended attribute is displayed when the help key is pressed. If 
both HM and HB are specified, the HB is ignored unless the 
help message has been specified for continuous display during 
the field read. 


The first and second substring are numeric values defining the 
position of the top left corner of the help box. Since the help 
box has a border, you should not enter zero for either 
coordinate. The remaining substrings each define a line of the 
help text. The box will automatically be made long enough to 
take the longest of these lines. 


HS Extended attribute — Spoken Help 


This extended attribute is currently only used in Amiga 
versions of PANEL Plus. The extended attribute string 
contains a single string to be passed to the translator and 
narrator devices. The passed string can contain escape 
sequences consisting of a vertical bar character followed by the 
single character ‘m’, ‘f’, ‘n’ or ‘tr’. for ‘male’, ‘female’, ‘natural’ 
and ‘robotic’ respectively. The default is ‘male’, ‘natural’. 


DF Extended attribute — Default Field Value 


The DF extended attribute is used to specify a default value for 
the field which will be inserted by the field prepare functions as 
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the field is prepared for display. If the field is a multi-line field 
the extended attribute string must consist of substrings for as 
many lines as are to be initialised. If it is a single-line field the 
extended attribute string should be a single string without 
substring delimiters. 


There are currently three initialiser strings for which special 
processing is performed: 


e TODAY! formats the current date into the field line as 
‘DD/MM/YY’. 


e TODAY? formats the current date into the field line as 
‘MM-DD-YY’. 

e TODAY3 formats the current date into the field line as 
“YYYY.MM.DD’. 


These formats can be changed in the source code for the field 
prepare functions. 


Additional User-Defined Extended Attributes 


Additional extended attributes, up to a maximum of 16, may be 
defined for user-specified purposes. 


The type of extended attribute is defined by its position in the 
table of attributes, but each also has a two letter code which is 
defined on line 202 of PANELP.MSG. New codes can be 
added to line 202 of PANELP.MSG as required, and the 
corresponding attribute can then be processed by user-supplied 
code. 
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THE PANEL PLUS SUBROUTINE LIBRARY 


This chapter describes the organisation of the PANEL Plus 
subroutine library and outlines the operation of each of the 
function groups. Full descriptions of each of the functions will 
be found in the reference chapters, together with specific 
details of the library format for each version of PANEL Plus. 


Library organisation 


The PANEL Plus library is normally delivered in the standard 
format for the linker used for a specific version of PANEL 
Plus. The library name is normally ‘panelp’; when a version 
contains several libraries (e.g. for different memory models) 
separate subdirectories will normally be used for the delivery. 
The library source is archived in some versions and delivered 
as separate modules in others. All of the library functions 
except three are common to all versions of PANEL Plus. The 
three exceptions are as follows: 


e Several versions of the screen output low-level 
functions are provided for different environments. 
The library will always contain one of these. 


e Several versions of the keyboard input low-level 
functions are provided for different environments. 
The library will always contain one of these. 


e Most versions of PANEL Plus have a compiler-specific 
module which isolates the lowest level operating 
system calls. For certain functions (currently only IBM 
Personal Computer memory-mapped screen 
operations) there is also an assembler module. 


Function types 


There are over 150 globally known functions in the PANEL 
Plus library. Luckily most programs written with PANEL Plus 
will need to use only a handful of these. The functions can 
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usefully be divided into seven groups and will be described and 
documented in these groups in this manual. 


The function groups are as follows: 


e Base functions. These are the only functions that will 
be used by many programs. They include such things 
as field preparation, display and read operations, as 
well as initialisation and termination of PANEL Plus 
operations. 


e Special functions. High level functions provided for 
special purposes, such as controlling pop-up menus or 
browsing a group of multi-line fields. 7 


e Validation functions. These functions implement the 
PANEL Plus data entry validation operations, and are 
designed to be changed and augmented to enable 
custom validation to be included in your applications. 


e PANEL-compatibility functions. We have provided 
some functions with the same names as in the PANEL 
library to ease the conversion of applications from 
PANEL to PANEL Plus. 


¢ Field primitive functions. These functions actually 
implement the heart of the PANEL Plus library. The 
majority of users will not need to modify these 
functions, but they are fully documented, and 
commented in the source, in case you need to do so. 


e Miscellaneous utility and service functions. Functions 
which are used to provide various services for the 
validation and other library functions. If you write 
custom validation routines, they may be useful to you. 


e Low-level I/O functions. The functions which actually 
manipulate the screen and keyboard. Some 
applications may find it convenient to call certain of 
these functions directly. 

The remainder of this chapter describes each group of 
functions. It may be sensible to stop after the base function 
group on a first reading of this chapter. 
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The Base Functions group 


The base functions are the functions that most application 
programs will need to use to manipulate screens and fields. 
There are 26 functions in this group. 


The first function in the group is pstart, which is called once at 
the beginning of your program before beginning screen and 
keyboard operations. It has a counterpart pfinish which is 
called once at the end of the program. In between, you may 
call pclear to clear the screen before moving on to another 
stage of your program. pclear will report an error if the screen 
contained fields displayed in overlay mode which you have 
failed to remove or dispose of properly. 


The main functions in the base group perform six field 
operations in each of three ways, making a total of eighteen 
functions in all. The three ways each operation can be carried 
out are as follows: 


e You can perform an operation on a single field, 
selected by passing a pointer to its field control block. 


e You can perform an operation on a list of fields, 
specified by passing a pointer to a null-terminated 
array of field control block pointers. 


e You can perform the operation on all or selected fields 
of a panel, by passing a pointer to the panel control 
. block. 


The six field operations performed by the functions are as 
follows: 


e Field Prepare. The field is prepared for display if 
required. Preparation can involve loading a default 
value into the data area, formatting a numeric field, or 
optionally clearing the field. 

e Field Display. The field can be displayed in one of two 
basic modes. In normal mode the field simply 
overwrites whatever was on the screen. In overlay 
mode the screen contents ‘under’ the field are saved 


TE A EE EL LT eee RT ee oe ee er 
THE PANEL PLUS SUBROUTINE LIBRARY Page 7-3 


The Base Functions group 


before display, thus allowing a ‘pop-up’ field to be 
subsequently removed. 


e Field Read. The operator is permitted to make entries 
in the field and edit existing data. Options allow 
scrolling if the field data area is larger than the field 
window on the screen. Validation functions are called 
for each keystroke, data character, and completed line. 


e Unshow Field. If the field has been displayed in 
overlay mode this function will remove it from the 
screen by redisplaying the saved previous screen 
contents. Any fields displayed on top of the overlay 
field“will also disappear, of course, whether or not they 
were displayed in overlay mode. 

e Lose Field. This operation disposes of the saved 
previous screen contents under an overlay field without 
redisplaying them on the screen. The function must be 
called for any fields displayed in overlay mode which 
are on the screen at a time you wish to clear the screen. 

e Field Fill to Blank. If a field has been delimited using 
a visible ‘fill’ character, this operation will change all 
fill characters to blanks. You might want to do this 
before storing the field data in a file for use by other 
programs. 

The naming convention for these functions is very simple: an 
‘f? as the third character indicates a single field operation, an ‘I’ 
indicates a field list, and a ‘p’ indicates a panel operation. The 
function names are as follows: 

e Field prepare functions: pafp, palp, and papp. 

e Field display functions: pafd, pald, and papd. 

e Field read functions: pafr, palr, and papr. 

e Field unshow functions: pafuf, paluf, and papuf. 

e Field lose functions: paflf, pallf, and paplf. 


e Field fill to blank functions: paffb, palfb, and papfb. 


Page 7-4 THE PANEL PLUS SUBROUTINE LIBRARY 


The Special Functions group 


The final functions in the base group are those used if you wish 
to dynamically load a screen layout instead of compiling and 
linking the data and control blocks with your application. The 
paload function will load a screen layout normally from a single 
panel file into dynamically allocated memory, and the pafree 
function will release the memory when you are finished with it. 
The pamlop and pamlcl functions will open and close a file 
from which you will be loading multiple screen layouts, and the 
palook function will find the panel you require in such a file. 


The Special Functions group 


There are currently only four functions in this group. The 
pamsge function displays a single-line prompt (passed as an 
argument) on a pre-defined ‘message line’. The corresponding 
paansw function retrieves an answer from the user into an 
‘answer space’ at the tail of the ‘message’. These functions 
implement a frequently-used method of obtaining initial 
application program input as distinct from full screen formatted 
data entry. 


The third function, pmenu, implements all commonly-used 
types of pop-up menus with moving highlighted bars. It returns 
a number corresponding to the user’s choice. The function can 
process menus with a highlight which moves horizontally along 
either words or word groups, menus with a vertically moving 
bar (when it can scroll over a larger field than the displayed 
lines), or combinations of both types. At the same time as 
processing the menu, pmenu can also scroll through a set of 
one-line menu item explanations, which it keeps in step with 
the highlighted bar. The objects which ‘pop up’ are of course 
single- or multi-line fields. 


The fourth function is a utility function which will vertically 
scroll a number of multi-line fields ranged across the screen. 
This technique is required for many applications — for 
example the item lines of an order which may contain separate 
fields for code, description, quantity and value, which must be 
scrolled together up and down to display more than will fit on a 
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single screen. The function, pabrw, is written to browse the 
fields and edit, insert or delete lines. Although it can be used 
‘as is’ it is really designed to be modified for specific 
applications, since it will often be necessary to refresh the 
fields’ data areas from an external data file in an 
application-specific manner. 


The Validation Functions group 


The PANEL Plus validation functions control four types of 
data entry validation which are implemented as exits from the 
main part of the function library. The entire validation process 
is defined by tables in the module pvtbl.c which contain 
function pointers. Validation can be changed dynamically by 
replacing function pointers in these tables, as well as by 
recompiling this module. 


Validation functions are not called directly by an application 
program. They are called from within the PANEL Plus library 
as required by the field specifications. 


The selection of a specific type of validation for a field is 
principally done by reference to validation parameters defined 
for the field when the screen layout is created. Each field can 
have a ‘character validation’ and a ‘line validation’ number. 
Each is by default used as an index into one or more of the 
function pointer tables, although custom validation functions 
may modify this usage. 


The four types of validation are as follows: 


e Key Validation. The key validation function is called 
for each keystroke encountered in a field read 
operation. It is often used to restrict the use of 
function keys in certain types of field. 


e Character Validation. The character validation 
function is called when a data character has been 
identified during a field read operation. Apart from 
obvious valid/invalid decisions, this function also 
incorporates an ‘unget’ feature which allows characters 
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to be emitted into the field. This feature is powerful 
enough to implement ‘word wrap’ on data entry as a 
character validation function. 


e Line Validation. Line validation is performed 
whenever a line is completed during data entry. Such 
operations as right-justification, and numeric validation 
and reformatting, are done in line validation, as well as 
checking of ‘date’ fields. This exit can also check the 
consistency of a complete multi-line field. 


e Field Validation. The field validation exit is provided 
to vary dynamically the path through a multiple field 
read operation. It makes it possible to implement a 
generalised feature such as ‘if this field contains “Y”, 
skip the next two fields’. 


The function names for validation functions are pkvnn, pevnn, 
plvnn, and pfvnn for key, character, line and field validation 
respectively. It is recommended that you follow this 
convention when writing your own functions. The special 
functions plvnv and panumvy used in numeric validation, and 
phelp to put up help information during key validation, are also 
members of this group. 


The PANEL-Compatibility Functions group 


Five functions are provided specifically to allow programs 
written for the PANEL library to be converted easily to run 
with PANEL Plus. All but the first make use of the array pafpt 
of field control block pointers. 


The panelf function performs a field operation defined by a 
function number and field control block. Each function is 
implemented using the PANEL Plus field primitives, but with 
only minor exceptions we have managed to maintain 
compatibility with the equivalent PANEL function. Since 
almost all of the PANEL Plus field functions are called from 
this function, your program may end up a little larger if you use 
it. 
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The pausep function loads the field control block pointers for a 
screen panel layout into a static array for use by panels to 
perform an operation on all fields. This static array is also used 
by pasenl which extracts the contents of a screen line for use in 
dumping the screen. 


Finally, the pamenu function is provided to avoid the need to 
make the minor changes to fields and call syntax which would 
be required to implement the new and more powerful pmenu 
function described above. 


The Field Primitive Functions group 


This group consists of 28 functions in which all of the PANEL 
Plus field operations are actually carried out. We expect that 
most PANEL Plus users will not need to modify these 
functions, but we do recommend that you use them when you 
write your own custom validation functions. 


All the functions have names starting pafi... The ‘i’ indicates 
that the functions operate on an ‘internal format’ field control 
block, which contains additional temporary fields for use in 
field operations. It is because the validation functions are 
passed an internal format field control block that it is simplest 
and most efficient to pass this on to any primitive functions you 
need to call during validation. 


The functions in this group, with very brief descriptions, are as 
follows: 

e pafip does a field prepare operation. 

e pafid does a field display operation. 

e pafir does a field read operation. 


e pafigp returns a pointer to the ‘current’ character in 
the field’s data area. 

e pafigs gets the contents of the ‘current’ line of the field 
into a string argument. 

e pafips puts a string into the ‘current’ line of a field, 
with right-justification if applicable for the field. 
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e pafiuf ‘unshows’ a field displayed in overlay mode. 


e pafilf ‘loses’ a field save area after display in overlay 
mode. 


e pafidf does a ‘fast’ display of part of all of the field 
(normally during a read operation) without 
redisplaying the field border, if any, and without 
changing any highlighting attribute bytes. 

e pafidh displays a field with the ‘current’ line specially 
highlighted. 

e pafihe displays the ‘current’ line only of the field, with 
special highlighting. 

e pafiuc displays the ‘current’ line only of the field, with 
the normal highlighting, if any, defined for the field. 


e pafidl deletes the ‘current’ line of the field in the data 
area, and closes up the remainder of the area. The 
field is not redisplayed. 


e pafiil inserts a line at the ‘current’ line of the field in 
the data area, and moves down the remainder of the 
area. The field is not redisplayed. 

e pafirn restores null bytes at the end of each line in the 
data area, if required, after a data manipulation 
operation. 

e pafidc clears the entire data area for the field to the 
defined fill character for the field. 

e paficf clears to fill characters the portion of the field’s 
data area which corresponds to the displayed screen 
area for the field. 

e pafifb changes any occurrences of the field’s fill 
character in the data area to blanks. 

e pafifr replaces any trailing blanks at the end of each 
line in the field’s data area with the field’s defined fill 
character. 


e pafifm replaces entry positions in a field’s entry mask 
with fill characters. 
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e pafimm creates a field entry mask using the positions 
of upward arrow (caret) characters in the data area. 


e pafich changes the highlighting of a field already 
displayed, if necessary by rewriting highlighting 
attribute bytes, but normally by redisplaying it. 

e pafier erases a field from the screen by writing blanks 
in its position and removing any highlighting attribute 
bytes. 

e pafilo performs the line validation operation on a field 
(named for compatibility with PANEL). It formats the 
defined numeric value(s) into the field. 


e pafish sets highlighting attribute bytes. 


e pafipl puts a numeric integer value into the ‘current’ 
line of the field. 


e pafipd puts a numeric currency value into the ‘current’ 
line of the field. 


e pafipn puts a numeric value as defined by the extended 
attributes of the field, into the ‘current’ line of the field. 


The Service Functions group 


This group contains miscellaneous service functions which may 
be useful during validation operations or in your application 
programs. A number of additional functions which are globally 
accessable but which are only called from within PANEL Plus 
library functions are not listed here but are documented in the 
reference section. 


The functions in this group, with very brief descriptions, are as 
follows: 


e pabm and pabf perform block move and block fill 
operations. If the compiler library includes fast 
assembler modules for these functions, they are used. 


e paix finds a character in a string in a standard way, an 
operation which tends to have different names and 
specifications in different C compiler libraries. 
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e panimp and panexp import and export field control 
blocks to or from ‘internal’ format. 


e pafgs gets a string from a field line, using a normal 
field control block. pafps does the opposite. 


e pafde clears the field data area, using a normal field 
control block. 


e pscana scans a field list to find a specific field name. 
It is usually used to find a field number for use with 
dynamically loaded screen layouts, when the field 
name is not known to the compiler. 


e ptelxy sets the column and row offsets to allow fields 
to be displayed in a position relative to another field. 


e pocode translates the return codes from PANEL Plus 
field read functions so that they correspond to those 
returned by PANEL read functions. 


e pasvin initialises the field save area for overlay fields 
and sets the number of areas to other than the default 
of 16. 


° paxasc and paxast scan a field extended attribute 
string to identify substrings and set the substring 
terminator characters to nulls. The latter function 
operates on a copy of the extended attribute string. 


e paxagn gets a numeric value from an extended 
attribute substring. 


The Low-Level I/O Functions group 


The low-level I/O functions actually perform screen and 
keyboard operations. There may be special circumstances 
which will require you to call some of these functions directly 
from your application program. Not all of the functions listed 
are provided in every version of PANEL Plus, but whenever 
possible inapplicable functions are provided as stubs which do 
nothing. 
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A number of additional functions which are globally accessable 
but which are only called from within PANEL Plus library 
functions are not listed here but are documented in the 
reference section. You should only need to refer to these if 
you are writing a low-level screen or keyboard module for a 
new environment. 


The functions in this group, with very brief descriptions, are as 
follows: 


pachcl changes the clear-screen color attribute. It is 
not provided in all environments. 


pacinp reads a single character from the keyboard. It 
allows a background function to be specified which is 
called while waiting for a character. 


pacout writes a character to the screen, with 
highlighting. 

pacsta tests the keyboard for character ready. 

pacurs positions the screen cursor for a read operation. 


paeout writes an escape sequence which is assumed 
not to move the cursor (unless it is a cursor command). 


pafunc performs a selected output function, such as 
initialising and de-initialising the screen, clearing the 
screen, clearing to end of line, sounding the bell, etc. 
The actual operations vary between different versions 
of the low-level screen module, but the general effect 
is common to all versions. 


pagetf gets a complete keystroke and interprets it as a 
function code or a data character. 

pagfin gets a field number at a screen position using 
the field tracking feature. 


painit initialises the PANEL Plus low-level screen 
operations, in some cases by reading a configuration 
file. 

pakini initialises the PANEL Plus low-level keyboard 
operations. 


Page 7-12 THE PANEL PLUS SUBROUTINE LIBRARY 


The Low-Level I/O Functions group 


e paosinit performs any operating system initialisation 
required for interactive screen input/output. 
e paosterm reverses the processing of paosinit. 


© papage switches display pages on the IBM color 
graphics adapter and compatible systems. 


e parout writes a ‘raw’ character to the screen, without 
highlighting. 

e pasbad sets the screen writing position and if possible 
turns off the cursor display. 


e pascse enables ‘screen save’ to allow field overlay 
operations to take place. 


e pasout writes a string of ‘raw’ characters to the screen, 
and flushes the output if buffering is being used. 
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Planning the screen layout 


Before you start to use the panelp editor program, you must 
decide how to organise your screen layout. panelp allows you 
to design a screen layout with up to 1000 fields on up to 127 
different overlapping levels, but we strongly recommend using 
separate screen panel files and limiting each screen to a few 
discrete ‘levels’. 


If you have an application which builds up a heirarchy of 
screens and subscreens, as many do, you should almost 
certainly break the application into separate screen layout files 
for each branch of your tree. Your program will be much 
easier to maintain and will also be more efficient in operation. 


If you follow this recommendation you may need to align fields 
from screen layouts which are stored in separate files. ‘To help 
you do this, panelp allows you to load one screen and save it as 
a ‘background’, then load another screen for editing. It is also 
possible to define a group of fields in the top left corner of the 
display, and then arrange for your application program to 
display them in an offset position, relative to another field. 
(You can also use this technique to display fields in a ‘pop-up’ 
area which may appear in different places on the display at 
different times). 


For a data entry screen, many people like to define one big 
field containing all the prompt fields on level zero, and then 
define separate input fields on another level. This method has 
the advantage of allowing the prompts to be set up very 
quickly, since you can move the cursor about all over the 
screen and type the prompts wherever you like. There are two 
main disadvantages, however: when your application changes it 
can be quite difficult to adjust and move fields to add or delete 
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a field, and displaying the screen can take substantially longer if 
all the blank spaces have to be written to display your big 
‘prompts’ field. 


We recommend defining each of your entry prompts as a 
separate field. The ‘T’ (type) command is used to do this, and 
allows you to create a field which is automatically sized to the 
length of your prompt text. Your entry fields have to be set up 
individually by specifying the beginning and ending point of 
each field. If you have a group of fields with similar attributes 
it is quickest to define one field and its attributes first and then 
copy the field to other positions on the screen, resizing and 
naming each field as required. 


When you have decided the overall strategy for designing your 
screen layouts you are ready to start creating the screens. 


Starting the panelp editor 


The command syntax for the panelp program is as follows: 
panelp [-z] [pnifile] 


There may also be alternate versions of the program with 
different names (for example the paneli program for faster 
memory-mapped operation on an IBM Personal Computer or 
compatible system). You can name on the command line the 
first screen layout which you wish to process, or enter it when 
requested. If panelp cannot find the corresponding .pni file it 
will ask you to confirm that it is a new screen layout. panelp 
then moves to ‘edit mode’ and, for a new screen layout, 
displays a blank screen with a prompt message. 


When loading an existing screen layout created with a version 
of PANEL earlier than version 6.00, you must use the -z switch 
on the command line. This switch sets the ‘level number’ of all 
fields to zero, which is necessary because the earlier files 
contained random data in the positions now used for level 
number. 
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If you normally keep screen layout (.pn/) files in a special 
subdirectory, you can set an environment variable named PNL 
to the full pathname of that directory, terminated with either ‘/ 
or ‘\’ as required by your operating system. This will enable 
you to enter only the file name and not the full path name 
when editing screen layouts. The extension ‘.pnl’ need never 
be entered, and in fact any ‘file extension’ is ignored. 


The panelp program has a main command mode from which 
you can select the following options: 


e Editing the screen layout. On first starting the program 
you bypass the command mode and go straight to this 
option. 

e Merge another screen layout. A file name is requested. 


e Write out the screen layout. The file name defaults to 
the original name entered, but can also be changed. 


e Use aclear background for the screen display. ‘This 
option is used to reset after a special layout has been 
used as a background to assist alignment of fields. 


e Switch to a new screen layout. Processing of the 
previous screen is complete. 


e Quit. Return to the operating system. 
The main command menu appears as follows: 


"DEMO": Edit Merge Write backGround New Quit [E/M/W/G/N/Q/?] _ 


The options are selected by keying the initial letter indicated in 
the prompt. In versions supporting selection by mouse button, 
you can move the mouse pointer to one of the letters separated 
by ‘/ characters at the end of the message, and press the left 
mouse button. In case of emergency, you should know that 
from the edit screen you need to key ‘escape’ to get back to the 
command screen from which you can quit. Context-sensitive 
help, which can be selected with the ‘?’ key, is provided for 
each panelp prompt. | 
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Creating fields 


The basic method of operation of panelp is that you move the 
cursor about the screen and then key a command letter which 
will take effect at the current position of the cursor. There are 
a number of ways to move the cursor: 


e The keys defined as ‘cursor arrow’ keys will move the 
cursor one position at a time. The left mouse button, 
when supported, will move the cursor to the position 
of the mouse pointer. 


e The space bar key is equivalent to ‘cursor right’. 

e The key defined as ‘tab’ will move the equivalent of 
eight ‘cursor right’ keys. 

e The key defined as ‘home’ will move first to the left of 
the screen and then to the top line. 


e The cursor ‘wraps’ at the edges of the screen. 


When no fields have yet been defined, there are only three 
options, to begin a new field, either manually or using 
automatic sizing, or to move the ‘prompt’ line: 


"DEMO": Begin Type Prompt ESC [B/P/esc/?] _ 


You should normally start by defining the ‘prompt line’ for the 
screen layout. If you plan to use the pamsge and paansw 
functions to display and read messages in your application, you 
should set the prompt line to the line you plan to use. If not, 
just move it to a line where it will not get in the way when 
panelp uses the line for its own messages. You move the line 
by positioning the cursor to the required line and then typing 
‘P’ (or by typing ‘P’ continuously until the line reaches the right 
position). 

To define and size a field manually, you next position the 
cursor where you want the top left corner of the field to be and 
type ‘B’ for begin. A caret symbol (‘*’) will be displayed, and 
the prompt changes: 

"DEMO": End field Abandon [E/A/?] _ 
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You can then either abandon the field with ‘A’ or move the 
cursor again to the end position for the field and type an ‘EP’. If 
you enter an ‘EP’, the field will be marked with all ‘*’ symbols, 
which panelp uses to represent blank fill. 


To initialise a field with automatic sizing, you can enter a “IT” to 
begin a field at the cursor position, and then type the 
initialisation data onto the screen. When you key ‘escape’ to 
terminate initialisation, a field is created which is automatically 
sized to encompass all the text you typed. Such a field is 
always created as a ‘no-input’ field. 


The prompt changes again, in recognition of the fact that there 
is now a field which can be edited and defined: 


"DEMO": Begin Prompt bkG Def Sel Type Info ESC [B/P/G/D/S/T/l/esc/#/?] _ 


Edit mode options 


It may be helpful to summarise at this stage all the available 
panelp edit mode options: 


e Begin a new field at the cursor position. 
e Move the Prompt line to the cursor line. 
e Save the current screen as the backGround. 


e Define the attributes or initialisation of the field under 
the cursor. 


e Select the field under the cursor for editing operations. 
e Type into a field using the automatic sizing feature. 


e Display Information about the field at the cursor 
position or about the screen layout. 


e Change to a different level #. 
e Escape to the main command screen. 


The selection, define, and information operations are initiated 
when the appropriate command is keyed with the cursor 
anywhere in the field. The type operation can be started to 
create a new field or to edit an existing no-input field. 
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In edit mode you can also use the keys defined as ‘insert 
character’, ‘delete character’, ‘insert line’ and “delete line’ to 
move all fields to the right of and below the cursor on the 
current ‘level’ (see below) by one column or row. 


Defining field attributes and initialisation 


The definition process is the most important part of designing 
the screen layout and will be covered in some detail. Field 
definition mode is entered by keying ‘D’ with the cursor inside 
the field. A further prompt menu is displayed: 


"DEMO": Name Init Fill Attr Seq Xtend Data End [N/I/F/A/S/X/D/E/?] _ 


Each type of field definition is selected by keying the indicated 
letter. When defining a new field you should work through 
each of the required definition options in turn. They are 
described in the following subsections. 


Naming the field. 


Only define a name for fields which you need to refer to by 
name in your application. The reason for this is that the only 
named fields appear in the header file generated by the code 
generator, and you do not need to tell your compiler about all 
of the prompt fields which you will never reference 
individually. If you do not name a field, it is assigned a unique 
field name beginning with ‘F_’. We advise against using this 
pair of letters at the start of your own field names, as it is 
certain to cause confusion. 


Field names must be different from the panel name, are 
limited to eight characters (starting with a letter), and must be 
unique both within a screen layout and among all screens which 
are to be compiled into one program. Since many applications 
use the ‘same’ field in several screen layouts, we provide a 
method to force uniqueness. A field-name prefix may be 
specified to the pangenc code generator with the switch 
‘-pprefix’, and this prefix will be applied to all field names in 
the generated code. This switch may also be stored in the 
‘note’ field which is specified when the screen layout is written 
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to disk. This method is strongly recommended since it avoids 
the problem of forgetting the prefix when you run the code 
generator. When stored in the ‘note’ field the prefix is also 
used by the enum and define generator utilities. 


Initialising the field 


Initialisation of a PANEL Plus field sets field contents which 
are normally used to define prompt fields. When initialisation 
is defined for an entry field it is forgotten after the first field 
read operation which changes it. (The ‘default’ extended 
attribute described later can be used to define a field value 
which is restored each time the field is prepared for use). 
Because initialisation is used mainly for prompt fields, the 
action of initialising a field for the first time automatically sets 
the ‘no input’ field attribute. If you subsequently delete this 
attribute to revert to an entry field, the attribute is not 
re-applied if the initialisation data is subsequently changed. 


Initialisation is carried out by entering data into the field using 
a normal read operation. If you have already defined entry 
attributes for the field (e.g. upper-case conversion) they will be 
applied. If you have removed the ‘echo’ attribute you will not 
see what you type. Use the escape key to end the initialisation 
process. 


If the initialisation contains caret (‘*’) characters it is 
considered to be a ‘mask’ with the entry positions limited to 
the positions containing the carets (which must be in the first 
16 positions in the field). Such a field does not automatically 
acquire the ‘no-input’ attribute. 


This initialisation function does not change the field size. If 
you need to edit the initialisation data in a way which requires 
the field size to be altered, use the ‘type’ command from the 
main editing menu, which automatically resizes the field. The 
‘type’ command is described later in this chapter. 
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Defining the fill character 


The ‘fill’ character for the field is defined either by typing the 
character itself, or its numeric ASCII value followed by 
‘return’. In the unlikely event of your needing a numeric 
character as a fill, you have to enter its ASCII value (e.g. ‘0’ = 
48). A blank fill character is displayed as carets, and caret 
itself is not allowed as a fill character. Also prohibited are the 
single and double quotes and the backslash character which can 
all cause chaos when we generate code to initialise your data 
area. (The code generator can correctly escape these 
characters in a data area initialisation, but a large number of 
them when used as a fill character can confuse some compilers). 


The fill character only affects the entry positions in a ‘mask’ 
field. 


Defining field attributes 


Field attributes are defined one after the other in five separate 
prompts and answers. First the entry attributes are defined by 
editing a string of attribute letters. Then the character 
validation and line validation numbers are specified as numbers 
from 0 to 255 inclusive. Finally the highlight type and modifier 
are defined. The highlight type selects one of 16 predefined 
highlight or colour combinations; the modifier modifies the 
selected highlighting in a manner that varies in different 
environments. The specification for the modifier is given in 
the documentation for the screen-level functions. 


The definitions of the standard entry attributes and validation 
numbers are documented in chapter 6. 


Defining a field sequence number. 


When a screen layout is written to disk, you can select one of 
three sequences for writing the fields, with the sort from top to 
bottom of the screen, from left to right, or in entry sequence. 
In all cases the major sort key is level number, and input fields 
precede no-input fields. 
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If these standard sort sequences are not appropriate, you can 
specify a sequence number for selected fields, which applies 
within each ‘level’. Fields for which a sequence number has 
been assigned are sorted, in sequence, ahead of fields without a 
sequence number (which are sorted in the selected output 
sequence). 


Sequence numbers can be any positive number from 1 to 
65535. To remove a sequence number, enter a zero. The 
numbers are stored in the screen layout file but only to control 
the sequence: they are not made available to application 
programs. 


Defining extended attributes 


Extended attribute specifications must fit within the defined 
area, and the first two characters of each extended attribute 
must be one of the character-pairs listed. You can continue an 
extended attribute over more than one line by entering *..’ in 
the first two columns of continuation lines. To delete an 
extended attribute, use the ‘erase to end of line’ key. 


Note that when code is generated for the screen layout each 
extended attribute is defined as a single string literal for which 
your compiler may have a size limit. If an extended attribute is 
to be divided into substrings, you should follow the identifier 
immediately with a delimiter character, and use the same 
delimiter between substrings and at the end of the string. It is 
vital not to omit the last delimiter, as this may cause strange 
effects in your program. 


For screen layouts to be used with the PANEL interface for 
Microsoft FORTRAN, the delimiter character for substrings 
must be either ‘\’ or ‘?. For the C language, any delimiter 
can be used. 


The definitions of the standard extended attributes are 
documented in chapter 6. 
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Defining the data area size. 


The data area for a field can be defined to be smaller or larger 
than the size of the display area for the field on the screen. 
The size is defined by entering the number of columns and 
rows separated by a comma. 


The only permitted size for a data area smaller than the display 
area (in either direction) is 1 by 1. Such a field may not be 
initialised, and if it is an input field it will be bypassed by the 
read functions. This type of field is used to define a ‘pop-up’ 
background window on which other fields can be displayed, 
without taking up more than one byte for a data area. 


The maximum field data area size is 255 rows by 255 columns. 
Be aware that defining fields this size will quickly increase the 
data requirements of your program. The maximum data area 
ageregate size for one panel is approximately 64kb. Fields with 
data areas larger than the display area can be initialised using 
the horizontal and vertical scroll features, but only the top lett 
portion will be displayed after initialisation is complete. 


Ending field definition 


The ‘E’ code returns you to edit mode. 


Selecting a ‘background’ screen 


In edit mode you can key ‘G’ at any time to save the current 
screen as a background. The background is redisplayed at any 
time the screen would otherwise be cleared and redrawn, such 
as after returning to edit mode from command mode, or after a 
‘define’ operation. The background is retained when you 
switch to edit a new screen layout from command mode. To 
revert to a normal ‘clear’ background you should escape to 
command mode and key ‘G’ from the main command menu. 


The use of a background screen can become confusing at times, 
as fields appear to be present when they are not in fact 
available for definition or selection. In addition, when you 
move fields on top of a background screen it leaves ‘holes’ in 
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the background. The background feature is provided solely to 
allow linking and alignment from one screen layout to another, 
and we recommend that you revert to a ‘clear’ background as 
soon as you have defined a couple of alignment fields on the 
second screen. 


Changing levels 


The PANEL Plus system allows fields to be defined on 128 
different ‘levels’, numbered from 0 to 127. Levels are simply a 
means of grouping fields. The fields on any one level must not 
overlap, so using multiple levels is essential if you want to have 
pop-up areas or fields which overlay each other. 


Level number zero is different from other levels in that fields 
on level 0 cannot be displayed in overlay mode. With any 
other level you can choose whether or not the field is displayed 
in overlay mode. This choice can either be made explicitly 
when you call a PANEL Plus display function, or can be related 
to the level number of the field: you can define an ‘overlay 
threshhold’ level number and fields above that level number 
will then automatically be displayed in overlay mode. You 
should be aware of these possibilities when designing the 
structure of levels for a screen layout. 


To select a new level number in panelp edit mode, you can 
simply type the single digit level number if the required level is 
from 0 to 9. For level numbers above 9, you have to type the 
character ‘#’ and then respond to a prompt for the level 
number. You can use the ‘#’ method for any level number, 
including 0 to 9. The current level number is shown in the 
prompt line, after the panel name. 


When panelp moves to level zero, all fields above that level are 
removed from the display. When you move to another level 
above zero its fields are added to those already displayed, 
overlaying existing fields. When the screen is redisplayed for 
any reason, the levels are redisplayed in the sequence in which 
you last ‘visited’ them. 
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If you forget which levels exist for a screen layout you can key a 
‘+? to move you from level to level. The ‘+’ moves to the 
next higher level above the current one which contains defined 
fields. If there are no fields at levels higher than the current 
level, the level number is not changed. 


The ‘#’ key also allows a group of fields to be moved from one 
level to another. When you are prompted for the level number 
you can precede the entered number with ‘>’, and this will 
cause all the fields on the current level to be moved to the 
entered level. A confirmation is requested before the change 
is carried out, since if there are already fields on the new level 
it may be difficult to reverse the operation. Fields which would 
overlap other fields on the new level are ‘left behind’ with their 
original level number, and a message is displayed. The current 
level number is changed to the new level. 


You can also move and copy an individual field from one level 
to another by selecting the field as described below and then 
changing levels before you move or copy it. 


Selecting fields for editing 


From edit mode a field at the current level is selected for 
editing by keying ‘S’ with the cursor anywhere in the field. The 
cursor moves to the top left corner of the field. A further 
prompt menu is displayed: 


"DEMO": Delete Copy Move End ceNter Abandon [D/C/M/E/N/A/?] _ 


Each field editing option is selected by keying the indicated 
letter. The options are described in the following subsections. 


Deleting a field 


The field is deleted by selecting the ‘D’ option. A confirmation 
is requested before the deletion is actually processed. 
Initialised no-input fields can also be deleted by using the 

‘type’ command described later in this chapter and clearing all 
the initialisation to blanks. 
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After selecting a field you can move the cursor to a new 
position and enter ‘C’ to make a copy of the field with its top 
left corner at the new position. The field must not overlap any 
other fields at the same level, or overlap the screen edges. If 
the source field has extended attributes defined you will be 
asked if you wish to copy them. All other attributes are copied 
automatically, and a new default name is assigned for the new 
field. 


Moving a field 


A selected field is moved by keying ‘M’ with the cursor in the 
position at which its top left corner is to be placed. Once 
again, the new position must not cause overlap with another 
field at the same level. All the field attributes and the field 
name are retained. Groups of fields can also be moved with 
the insert/delete line/character editing keys described above. 


Reshaping a field 


A selected field can be reshaped by keying an ‘E’ at the new 
position for its bottom right corner. If the field data area is the 
same size as the display screen field then it is also reshaped to 
match. If the field data area is larger than the display screen 
field it is enlarged only if a dimension of the new screen field is 
larger than the corresponding data area dimension; otherwise 
the data area size is left unchanged. You will be asked for 
confirmation before an initialised data area is reduced in size. 
If you have changed to a different level after selecting the field 
the ‘E’ operation will not be allowed. 


Initialised no-input fields can also be reshaped using the ‘type’ 
command described later in this chapter. After typing in new 
initialisation data the field is automatically reshaped to match 
the extent of the data. 
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Centering a field 


A selected field can be moved to the middle of the screen 
(without changing its screen row) by keying ‘N’. The operation 
is exactly the same as a ‘move’, but with an automatically 
calculated target position. 


Abandoning a selection 


Keying ‘A’ will abandon the operation if you decide not to 
process a selected field. 


Typing initialisation data with automatic sizing 


The ‘typing’ mode is a PANEL Plus feature which combines 
field creation, initialisation, sizing, reshaping, and deletion in 
one simple operation. It is designed for use with the ‘fixed 
text’ on a data entry screen. 


The ‘T’ key is used to enter ‘typing’ mode. You can key a “I” 
in one of two positions: 


e Outside any field 


e Inside an initialised, no-input field which has the ‘echo’ 
attribute set. 


The ‘T’ key will not be accepted unless one of these conditions 
applies. If the ‘T’ is keyed inside a field, the cursor is moved to 
the start of the field and if the field is not already highlighted 
its contents are ‘flashed’ to indicate the current extent of the 
field. The function opens up an ‘invisible’ field which extends 
from the cursor position to the bottom right corner of the 
screen. Any existing fields in that area remain visible unless 
you overtype them or ‘space’ over them. The keys for insert 
and delete character and line, and erase to end of line, are not 
available because they would paint blank spaces from the 
‘invisible’ field over existing fields. (The ‘define - initialise’ 
command sequence can be used if you need these operations). 


When you key ‘escape’ to terminate entry of the initialisation 
data, the field is automatically sized by scanning the non-blank 
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characters to find the smallest surrounding rectangle. The top 
left position of the field is not changed in this operation. For 
an un-highlighted field, the calculated area is ‘flashed’ 


If the automatically-determined end position for the field 
overlaps another field on the same level, an error message will 
be displayed and you will have to space over the overlapping . 
part of the data before you can exit. The screen 1s completely 
repainted on exit in case you have typed or spaced over other 
fields. 


If the entire field is cleared to spaces you will be asked to 
confirm that it is to be deleted. If you enter no data for a new 
field, or clear to spaces all that you entered, no field is created 
when you type ‘escape’ to terminate entry. 


When a new field is created with the “T’ command, it is given 
attributes of init’, ‘no-input’, and ‘echo’, and a default name is 
generated. Note that only one field is created, even if your 
input text contains ‘gaps’. 


Information display 


In edit mode, keying an ‘I’ when the cursor is in a field at the 
current level will display information about the field’s position, 
size and attributes. This can save counting positions on the 
display to check the field size. A sample of the display is as 
follows: 


"DEMO": NADR: X= 20 Y=7 L=36/52 H=5/10 XA INPUT E 0: [Key <sp>] _ 


If the field data area size is different from the display area, the 
length and height will be shown as two values separated by ‘/’. 
The first value is the screen size and the second is the data area 
size. 


When the cursor is not inside a field, keying ‘I’ displays 
information about the number and aggregate size of fields, and 
the number of levels in use, as in: 


"DEMO": FIELDS 33 (INPUT: 10, SIZE: 912) # LEVELS: 6: [Key <sp>]_ 
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Merging another screen layout 


From the main command menu you can key “M’ to merge 
another screen layout with the current one. Fields which 
overlap will be omitted, and duplicate field names will be 
changed to a default generated name, in each case with a 
message displaying what has happened. 


Writing screen layout details to disk 


Keying ‘W’ from the main command menu starts the process of 
writing out the screen layout. First the fields are checked to 
ensure that the sum of the number of fields and the total data 
area is less than 64kb. If this limit is exceeded you will have to 
go back to edit mode and remove some fields or reduce their 
SIZe. 


The name to be used for the output .PNL file defaults to that 
of the input file, but can be changed if you wish. If a file exists 
with the selected name it will be renamed with a .PNB 
extension. 


You will next be prompted for a ‘note’ or ‘description’ to be 
saved with the screen layout. You can use this field for a 
comment. If you wish to apply a unique prefix to your defined 
field names you can specify a switch of the form “-pprefix’ which 
will be used by the code generator. 


The switch ‘-nxx’ can also be specified and will cause the 
default ‘F ’ in field names to be replaced by the (one- or 
two-byte) string xx. (The ‘-n’ switch is not normally required 
for C language code generation as any field with a name 
starting ‘F ’ will be defined as static, so that no name conflicts 
will occur between source modules). Then a further prompt 
appears: 

"DEMO": Fleld scan: Vertical Horizontal Unchanged [V/H/U?] _ 


The final question you are asked before the screen layout is 
written out concerns the field sequence for output. The field 
sequence selected controls the default order in which fields are 
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presented for input in a full-screen read operation. Fields are 
always written in sequence of level number, with input fields 
preceding no-input fields. Within this overall sequence there 
are three options: 


e Horizontal sequence. The major sequence is from left 
to right. The minor sequence is from top to bottom. 
This means that the overall direction is from left to 
right, but fields starting in the same column will be 
processed from top to bottom. 


e Vertical sequence. The major sequence is from top to 
bottom. The minor sequence is from left to right. 
This means that the overall direction is from top to 
bottom, but fields starting in the same row will be 
processed from left to right. 


e Unchanged. The field sequence within each level is 
the same as when the screen was input, with new fields 
added in order of creation. 


If you specify sequence numbers for individual fields the fields 
with sequence numbers are sorted ahead of those without 
sequence numbers. If you have deleted a sequence number you 
should always select the horizontal or vertical sort, since 
‘unchanged’ does not mean ‘put it where it would have been if 
it had not had a sequence number’. The sort only affects the 
output file: if you return to edit a screen layout after writing it 
Out the sequence will not have changed. 


Editing a new screen layout 


You can switch to editing another screen layout after entering 
‘N’ at the main command prompt. A new screen layout file 
name is requested, which may be an existing layout or one 
which you want to create. Nothing is remembered about the 
previous screen layout except any defined background (which 
can be cleared when no longer needed with the ‘G’ command 
at the main program prompt. 
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Terminating the panelp editor program 


The program is terminated by entering ‘Q’ at the main 
command prompt. You will be asked to confirm that you wish 
to exit unless you have selected no other options since last 
writing out the screen layout. 


niente a 
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This chapter describes the various utility programs supplied 
with the PANEL Plus system. 


The pantest program 


The pantest program allows you to exercise a screen layout for 
both testing and documentation purposes. It reads in a panel 
file using the dynamic load feature, displays it, and allows 
entries in each input field. This allows you to check if your 
attributes and validation are correct. 


The command syntax for pantest is as follows: 


pantest [pnifile] 


pantest can accept a panel file name on the command line, or 
will prompt for a name if none is given. 


The program is supplied in source form (PANTESTC.C) so 
that it can be compiled and linked with special validation 
routines. You can also create special versions of pantest linked 
with different low-level screen and keyboard modules, for 
example using graphics mode with one of the supported 
graphics library products. This enables you to test the 
appearance of your screen layout in the correct target 
environment. 


Alternate versions of the program may be provided, such as the 
pantesti program which operates in memory-mapped mode on 
an IBM Personal Computer and supports a mouse. In versions 
of pantest which support a mouse, the left mouse button can be 
used to reposition the cursor in a field and to move between 
fields on level zero, as well as to select one of the letters 
separated by ’/ on the main command prompt line. 
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After processing the fields defined at level zero you can display 
and read data for other levels. The levels are selected by 
keying ‘#’ at the main prompt and responding with the level 
number when requested; levels 1 to 9 can also be selected by 
keying the level number at the main prompt. The screen 
display can be printed, or written to a text file to assist with 
application documentation. The text file is named 
PANTEST.TXT and any existing file of that name will have 
data appended. 


The program can process multiple screen layouts in one 
invocation, either in separate files or in a multiple file with 
index as created by pnlindx. If the screen layouts are in 
separate .PNL files, the ‘N’ command on the main prompt line 
can be used to select a new screen layout. To use multiple file 
mode, the following command syntax is used: 


pantest -m multiple index 


The switch -m is specified, and both the multiple panel file and 
its index file are named on the command line. In multiple 
panel mode the ‘N’ command is still used to specify a new 
panel name, and the program uses the index to find the screen 
layout in multiple. 


The pnlindx program 


The pnlindx program builds an index to a data file containing 
multiple panel files. The data file is first built by 
concatenation: use a command such as: 
copy a*.pnl/o+b*.pni multiple = [MS-DOS, PC-DOS] 
cat a*.pnl b*.pn! multiple [UNIX, XENIX] 


Both the above commands create a file named ‘multiple’ which 
contains all the panels with names beginning with ‘a’ or ‘b’. 
The ‘/b’ switch is essential for the DOS copy command. 

The command syntax for pnlindx is as follows: 


pnlindx [-v] multiple index 
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The pnlindx program creates index from multiple containing 
the panel names and starting record numbers. The -v option 
displays panel names as they are encountered. 


Index files created by pnlindx are not portable between 
machines using different byte sequences for two-byte integers. 


Note that screen layout (.PNL) files which are to be indexed 
with pnlindx should only be renamed by rewriting with panelp, 
since pnlindx uses the internal panel name to create the index. 
Do not use the operating system rename or mv command. 


The enum program 


The enum program writes a file to stdout with source code 
consisting of an enum statement. The intention is to provide a 
correspondence between field name and field number for use 
when a screen layout is loaded dynamically and so field names 
are not available to the application program. 


The command syntax for enum is as follows: 


enum pnifile [ pnifile.h ] 


The program requires a command-line argument consisting of a 
single .PNL filename. The .PNL extension should not be given. 
If a field name prefix is found in the ‘description’ field for the 
screen layout, it is used in the generated field names. 


The define program 


The define program writes a file to stdout with source code 
consisting of #define statements. The intention is to provide a 
correspondence between field name and field number for use 
when a screen layout is loaded dynamically and so field names 
are not available to the application program. The output from 
this program can be used if your compiler does not support 
enum. 


The command syntax for define is as follows: 
define pnifile [ pnifile.h ] 
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The program requires a command-line argument consisting of a 
single .PNL filename. The .PNL extension should not be given. 
If a field name prefix is found in the ‘description’ field for the 
screen layout, it is used in the generated field names. 


The document program 


The document program writes a file to stdout with header 
information about the screen layout and a line of 
documentation for each field. The documentation includes the 
position, dimensions, and level number of each field, together 
with abbreviated information about field attributes. 


The command syntax for document is as follows: 


document pnifile [ pnifile.h ] 


The program requires a command-line argument consisting of a 
single .PNL filename. The .PNL extension should not be given. 
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This chapter describes how to generate C code to describe 
PANEL Plus screen layouts. 


The pangenc program 


pangenc generates C structures and arrays to define the fields 
in a screen layout. Two files are normally created, an ‘H’ file 
to be included in your application to give access to named field 
data areas and field control blocks, and a ‘C’ file which is 
compiled to define and initialise all the structures and data 
areas. 


The command syntax for pangenc is as follows: 

The output files from pangenc are named PNLFILE.C and 
PNLFILE.H. Existing files are overwritten. The code 
generation process is controlled by the program options, which 
may be specified at two stages: as defaults on line 9 of 
PANGENC.MSG, or on the pangenc command line. Options 
may be entered as separate switches each preceded by a 
hyphen, or as a block of letters following a single hyphen, 
except as indicated below. 


Options are all ‘toggles’, and specifying an option an even 
number of times is therefore a waste of effort. Line 10 of 
PANGENC.MSG defines (in upper-case letters) the option 
letters which are accepted on the command line: this feature 
can be used to restrict operator entry of options to those 
appropriate to the environment. 


Words on line 9 of PANGENC.MSG not starting with a — 
hyphen are ignored and may be used as comments. Options 
may follow a hyphen in sets or individually. The case of option 
letters is not significant. pangenc processes only the first 15 
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tokens (filename or option set) encountered at each stage. 
Only one file may be processed by pangenc at each invocation. 


Some of the option descriptions below will only be of interest 
to experienced C programmers who wish to port generated 
code between different compilers. The version of 
PANGENC.MSG supplied for each environment will define 
appropriate options for that environment. The switches most 
often required in day-to-day use of pangenc are the -f and -p 
switches, but the latter, if used, will normally be coded in the 
panel comment field. 


e The -a switch controls the initialisation of character- 
string pointers. The default setting generates code 
with ampersands: 


&SNAME[0], &MULTILINE[0] [0], 


and the modified setting generates: 
SNAME, MULTILINE. 


e The -b switch controls the generation of nested braces 
for initialisers in the panel control block. The default 
is to use nested braces as in K&R 8.6. The modified 
setting omits the inner braces. 


e The -c switch controls the generation of nested braces 
for initialisers for multiline fields. The default is to 
use nested braces as in K&R 8.6. The modified setting 
omits the inner braces. 


e The -d switch radically changes the layout of the 
generated code. The ‘H’ file contains full definitions 
and initialisation for all fields, with the initialisation 
conditionally excluded when the module is included in 
your application program. The C file sets a define to 
force compilation of the initialisers, and then simply 
includes the ‘H’ file. The advantage of this option, 
which was the default in older versions of PANEL, is 
that all the generated code appears in one place. 
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e The -e switch generates an enum set in the *.H’ file to 
cross reference assigned field names to field numbers. 
No entry appears unless a field name other than the 
default name appears. 


e The -f switch causes ‘full’ field control blocks to be 
generated. The default is ‘abbreviated’ field control 
blocks, which omit the field name and certain other 
fields. 


e The -g switch is used with compilers which object to a 
cast on a constant initialiser. 


e The -h switch avoids nesting include files when using 
the D option. 


e The -i switch generates quotes instead of angle 
brackets on the include statement generated for the 
‘H’ file with the D option. 


e The -k switch causes characters in string initialisers 
which have their high bit set to be generated in 
escaped octal format. | 


e The -l switch causes character string initialisers to be 
expanded as required to match exactly the declared 
string length. It is required for the QNX C compiler. 


e The -n switch must be entered singly, or at the end of a 
block of switches, since it uses the letters following the 
option letter, up to the next white space, to replace the 
‘F’ (if one) or the ‘F’ and the following underscore (if 
two) for automatically generated field names. This 
avoids duplicate field names between panels when 
using the -d switch. The -n switch and following letters 
may also be placed in the panel comment field. 


With the default setting of the -d switch the -n switch 
is unnecessary, since any fields not given an explicit 
name are defined as static. 


e The -o switch selects generation of the old fcb format, 
excluding extended attributes, for use with versions of 


oo OR ae A ot ee a a SS eee eee ees 
CODE GENERATION Page 10-3 


The pangenc program 


PANEL earlier than 5.30. Any extended attributes 
present are ignored. 


e The -p switch must be entered singly, or at the end of a 
block of switches, since it uses the letters following the 
option letter, up to the next white space, as a prefix for 
all non-default field names for the screen layout. This 
allows the same field name to be used in multiple 
screens which are to be linked into one program. The 
-p switch and following letters may also be placed in 
the panel comment field. 


e The -q switch was provided for early versions of the 
QNX C compiler, which required structure initialisers 
to be specified as if the structure was an array of ints. 


e The -r switch selects quotes instead of angle brackets 
for the include statements generated for PANEL Plus 
header files. This option used to be selected by the -p 
switch in PANEL. 


e The -s switch changes the byte sequence of the 
initialisers for the sa and sm fields in each field control 
block. Although .PNL files are portable, the bits in 
these fields have different significance for each 
processor type. For example, you should use the -s 
switch when you generate code on an 8086 which is to 
be compiled on a 68000. 


e The -x switch causes an executable function to be 
generated in the ‘C’ file, which can be called to force 
loading of the module in an overlay environment. 

If you wish to experiment with the above options, remember to 
check PANGENC.MSG to see what options are already in 
effect (line 9) and which are allowed to be entered (line 10). 
WARNING: some compiler/option combinations are 
spectacularly incompatible. 
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PROGRAM 


When you actually come to link together programs you have 
created incorporating PANEL Plus, it is not always obvious 
how to build the executable program. 


There are now so many compilers supported that is not 
practical to document here all of the possible linkage 
commands. Instead we have provided makefiles for most of 
the supported environments, which not only rebuild the 
PANEL Plus library but also link some sample programs. If 
you do not have a make utility you will have to extract the 
action lines and enter them manually. 


Note that the supplied makefiles will almost certainly require 
amendment before you can use them with your own directory 
structures and utility programs. Since this would be the case 
whatever makefiles we provided, we took the view that it was 
better to ship the actual makefiles we use to build and test the 
PANEL Plus libraries, so that we do not have the task of 
keeping in step both ‘real’ and ‘vanilla’ makefiles. 


The example makefiles create the pantest and teste programs, 
assuming that the code generator pangenc has already been run 
to create DEMO.C and DEMO.H. 


Checklist for linking programs 


The general principles of linking PANEL Plus programs are as 
follows: 
e list all your application program object modules as 
input files. 
e add the object files for the compiled code which has 
been generated by pangenc. 
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e add any PANEL Plus library or validation modules 
which you have modified and recompiled but which 
have not been added into the PANEL Plus libraries. 


e specify the PANEL Plus library file (usually named 
panelp) preceded by any override files for special 
environments (e.g. the panelpi file for 
memory-mapped operation on the IBM Personal 
Computer and compatible systems). This sequence iS 
essential: the main panelp library must be the last 
PANEL Plus library mentioned. 


e specify the library files for any other packages you are 
using, such as for file management or graphics. 
Graphics versions of PANEL Plus may make calls to 
the graphics library, which must therefore be specified 
after the PANEL Plus library. 


e specify the compiler libraries, if necessary. For UNIX 
and Xenix and similar systems these libraries are 
automatically included by the cc command, and some 
MS-DOS compilers insert automatic library search 
commands in the object files as necessary, but if your 
compiler does not do this you must name the required 
compiler libraries last of all. 


Most problems with linking can be resolved by using the above 
list as a checklist. You may also need to refer to your compiler 
and linker documentation. 
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PANEL PLUS HEADER FILES, DEFINES AND 
VARIABLES 


This chapter documents the PANEL Plus header files and the 
various preprocessor and variable definitions they contain. 


PANEL Plus header files 


Header files are used for three main purposes in PANEL Plus: 


e To ease porting of applications between different 
operating system and compiler environments. 

e To ease selection of PANEL Plus compile-time 
options. 

e To provide standard structure and function prototype 
definitions. | 

Most application programs will only need to include one 

header file, PANEL.H, which will then include all the 

necessary definitions. For compilation of PANEL Plus library 
modules, and porting applications, you may need to modify 
individual header files. The full list is as follows: 

PANEL.H This file includes the portability header files 

: pnli and pnie, and the field and panel structure 
definition files pfeb and ppceb. It also includes 
external variable and function definitions for all 
of the most commonly used PANEL Plus 
functions. The vast majority of application 
programs will get by by simply including this 
one file. 

PCS.H The pes header file contains variable and 
function definitions for the low-level 
compiler-specific functions, and should be 
included by a module which makes direct calls 
to them. 
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PFCB.H The pfcb header file contains structure 
definitions for all types of field control blocks 
and associated structures, as well as all the 
special named values used in field processing. 


PFI.H The pfi header file contains variable and 
function definitions for the field primitive 
functions, and should be included by a module 
which makes direct calls to them using internal 
format field control blocks. 


PFLIST.H The pflist header file contains variable and 
| function definitions for the field list processing 
and dynamic load functions. 


PKB.H The pkb header file contains variable and 
function definitions for the low-level keyboard 
functions, and should be included by a module 
which makes direct calls to them. 


PNL3.H The pnl3 header file is provided for 
compatibility with PANEL programs. It 
includes pfcb.h to define field control blocks, 
and then defines the named values for the 
panelf function. 


PNL5.H The pnl5 header file is provided for 
compatibility with PANEL programs. It 
includes ppcb.h to define panel control blocks, 
and then defines the named values for the 
panels function. 


PNLC.H The pnlc header file is a portability header file 
defining the characteristics of each processor 
and operating system. The processor and 
operating system is made in the pnli header file, 
and used in pniec. Details of a new processor or 
operating system should be added here. 
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PNLI.H The pnli header file is a portability header file 
defining the characteristics of a specific PANEL 
Plus implementation. This file should be used 
to specify the required compile-time options 
and compiler-specific features, and should also 
define the processor and operating system for 
use in the pnlc header file. A separate pnli 
header file is provided for each PANEL Plus 
implementation, and you would need to write or 
adapt your own file if implementing the 
PANEL Plus library in a new environment. 


PPCB.H The ppcb header file contains the structure 
definition for a panel control block. The fcb 
pointer array size can be changed by defining 
PCBFLDS as the required value. 


PSC.H The psc header file contains variable and 
function definitions for the low-level screen 
functions, and should be included by a module 
which makes direct calls to them. 


PUPC.H The pupc header file is provided for PANEL 
compatibility and contains translations from 
upper to lower case of all PANEL names which 
have an equivalent PANEL Plus name. You 
should include this file when recompiling a 
PANEL application for use with PANEL Plus if 
your compiler/linker combination is 
case-sensitive. 

PVAL.H The pval header file includes a selection of 
other include files, and variable and function 
definitions, for use when compiling PANEL 
Plus validation modules. It also provides 
symbolic names for extended attribute numbers. 
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PANEL Plus pre-processor defines 


This section will attempt to classify and explain all of the pre- 
processor define symbols used in the PANEL Plus system. 
Although there may seem to be a large number of these 
symbols, their presence actually simplifies the business of 
recompiling and porting PANEL Plus source modules. 


All but a small number of symbols are booleans, that is they 
are either undefined or defined with a value of 1. If this 
documentation mentions no explicit values, a boolean symbol 
should be assumed. 


There are a number of symbol classes which do not need 
detailed discussion: 


e Each PANEL Plus header file defines and tests a 
symbol, to allow the file to be included multiple times 
without causing an error (this practice therefore only 
slows down your compiler). The symbols defined 
normally have the same name as the header file, and 
currently comprise PANELH, PCS, PFCB, PFI, 
PFLIST, PKB, PNL3, PNLS, PNLC, PNLI, PSC, 
PUPC and PVAL. 


e Each version of the pnli header file normally defines a 
symbol to represent the processor group, unless 
automatically defined by the compiler. Current 
defined symbols are 18080, 18086, PDP11, VAX, 
M68000, Z8000, WE32002 and IBMROMP. Some of 
these may not represent current versions of PANEL 
Plus. If you move PANEL Plus programs to a new 
processor, you can keep things neat by defining a new 
symbol in the pnli header file and inserting details of 
the processor byte sequence in the pnlc header file. 


e Each version of the pnli header file normally defines a 
symbol to represent the operating system type, unless 
automatically defined by the compiler. Current ee 
defined symbols are AMIGA, IRMX86, MSDOS, QNX, 
UNIX, VMS, WSL (Whitesmiths), and XENIX. Some 
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of these may not represent current versions of PANEL 
Plus. If you move PANEL Plus programs to a new 
operating system, you can keep things neat by defining 
a new symbol in the pnli header file and inserting 
details of the operating system characteristics in the 
pnic header file. The additional symbol NIX is used to 
signify any UNIX-like operating system. [These 
operating system names are in most cases trade marks 
of the authors]. 


e Each version of the pnli header file normally defines a 
symbol to represent the compiler manufacturer, unless 
automatically defined by the compiler. Current 
defined symbols are AZTEC, LATTICE, 
MARKWILLIAMS, MSC (Microsoft), and WIZARD. 
Some of these may not represent current versions of 
PANEL Plus. If you move PANEL Plus programs to a 
new compiler, you can keep things neat by defining a 
new symbol in the pnli header file. The symbol is 
mainly for documentation and is rarely tested. [The 
compiler names are in most cases trade marks of the 
authors]. 


e When a specific compiler or environment has a ‘special 
feature’ which requires non-standard code we define a 
symbol of the form CFnnn, standing for ‘compiler 
feature’. This enables us to include work around code 
for these special cases. The situation is usually 
documented in the version of the pnli header file 
which defines the symbol. 


e The pfcb header file contains a number of define 
values for field functions, field list functions, and the 
contents of the field attribute (sa) field in the field 
control block. These defines are documented in the 
header file and in the function descriptions. 


The remaining defines will be described in a little more detail 
in the remainder of this section. The first group consists of the 
defines which are used to describe operating system and 
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processor characteristics. Most of these are defined in the pnle 


header file. 


BACKSLASH This define indicates that the path element 


BYTESWAP 


CURSHAPE 


DATETIME 


ENVIRON 


FKNUMB 


FLUSH 


separator character is a backslash (‘\’). 
Otherwise, PANEL Plus assumes that the path 
separator is a slash (‘/’), for operating systems 
that have path elements at all. 


If this is defined then bytes in a two-byte 
integer are stored in the opposite sequence to 
that used by the 8086 and the VAX. At the 
same time the macro definition SWAP(x) will 
call the paswap function. The default, when 
BYTESWAP is not defined, is that SWAP(x) 
evaluates to (x). 


When defined, CURSHAPE indicates that this 
implementation has the ability to alter the 
screen cursor shape. The alternate shape can 
then be used to indicate that ‘insert mode’ is in 
effect. 


This indicates that a system date and time are 
available from the operating system. 


When defined, the operating system supports 
environment variables as a means of passing 
character strings to an application, normally via 
a function such as getenv. 


This define indicates that the keyboard 
recognition functions should process enhanced 
ANSI escape sequences in which function keys 
are represented by a numeric value embedded 
in an escape sequence. It is currently used only 
for the IBM 6150 RT PC. 


When set, this define causes PANEL Plus 
screen output to be buffered and flushed at 
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intervals. The default is to make one operating 
system call to output each character. Normally, 
but not always, this define should be set for 
UNIX and similar operating systems to provide 
the best performance. 

LOWFILE This indicates that the operating system 
generally uses lower case file names. 


NEWLINE When set, it indicates that the operating system 
generally uses a single newline character in text 
files, as opposed to a <cr> <If> combination. 


NOKS The NOKS define is set when the operating 
system does not provide any keyboard status 
(character waiting) indication. 


The next group is used to set options for PANEL Plus 
compilations, generally to include features which may not be 
required in certain versions. These symbols are normally 
defined in the pnli or pnic header file when required. 
ATTBYTES — The low-level output routines and the 
field-level routines will only support 
highlighting attribute bytes when compiled with 
this define set. Attribute bytes are generally set 
with escape sequences and take up a position 
on the screen. When this type of highlighting is 
supported, it is incompatible with several 
important PANEL Plus features, including field 
borders and field display in overlay mode. 
FIELDTRACK Setting FIELDTRACK results in the inclusion 
of code which maintains a screen map showing 
the field number currently displayed at each 
position. 
IBMBIOS Setting IBMBIOS for the PSC01.C source 
module results in the inclusion of code which 


PANEL PLUS HEADER FILES, DEFINES AND VARIABLES Page 12-7 


PANEL Plus pre-processor defines 


implements screen output using IBM Personal 
Computer ROM BIOS calls. 


NOGRAPH _ Defining this value excludes the calls in the 
field display primitive function which ask the 
low-level output functions to display a graphics 
border round a field. You can save some time 
and space if you know that a specific version 
will always be linked with routines which 
decline this request. 


PCBFLDS This symbol can defined as a numeric value 
| which is the size of the field control block 
pointer array in PPCB.H, when subsequently 
included. It defaults to 258. 


PPROTO The definition of this symbol causes the 
function prototype variants of external function 
definitions to be used in the header files. 


TAILOR This define is set when compiling versions of 
the PSC01.C and PKBO1.C modules for use in 
the tailor program. 


USEFLOAT The USEFLOAT define causes the processing 
of currency fields to be done with double 
variables instead of with long variables 
displayed with an implied decimal point. If you 
define this symbol in your header files, you 
must recompile the library module PLVNV.C. 
The state of the USEFLOAT symbol controls 
affects the definition of the associated symbol 
DOLLAR, which is defined in the pval header 
file. 

USEFOP This symbol forces files read in the PANEL 
Plus library modules to be opened with fopen 
instead of open calls, if the latter are not 
provided in the compiler library. 
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The final group of defines also includes important 
compiler-specific typedef statements and macros which it is 
absolutely essential to get right when porting PANEL Plus to a 
new environment. They must always be defined in the pnli 


header file. 


VOID 


PANULD 


PANULF 


PAOMOD 


uchar 


UCI(x) 


The symbol VOID should be defined as void if 
your compiler supports this, and as int otherwise. 


The symbol PANULD must be defined as 
something acceptable to your compiler as a null 
data pointer. 


The symbol PANULF must be defined as 
something acceptable to your compiler as a null 
function pointer. 


The symbol PAOMOD must be defined as the 
value in an open call which will open a file for 
input in binary (untranslated) mode. 


The typedef for uchar must define it as an 
unsigned one-byte variable taking values from 0 
to 255. If your compiler does not support this, 
or if you do not know whether it supports it or 
not, you should define it as a normal char and 
code the UCI macro as described below. 


This macro must convert objects of type uchar 
to integers or unsigned integers without 
sign-extension. In other words a hexadecimal 
value of Oxff in a uchar variable must be 
converted to a value of 255, and not to a value 
of -1. 


If your compiler supports a true unsigned 
character, you can define UCI(x) as simply (x). 
If not, or if you are in any doubt, define it as (x 
& Oxff). We have also found compilers which 
under certain circumstances do 8-bit arithmetic 
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uint 


on such variables (i.e. do not promote to int). 
In such cases you should use a cast and define 
this macro as ((uint)(x)). 

The typedef for uint must define it as an 
unsigned two-byte variable taking values from 0 
to 65535. On 8086 systems this will normally be 
an unsigned int and on others an unsigned short. 


PANEL Plus global variables 


The PANEL.H header file contains a set of external variable 
definitions which cover the majority of application program 
requirements. The variables in that file are summarised here, 
but full descriptions of the use of each variable also appear in 
the documentation of the function(s) that it affects. 


paflx 


paflxs 


pakbfp 


pakcln 


paflx is set to a non-zero number to indicate the. 
element in a field pointer list at which a field 
read operation should commence. Setting a 
value of 1 starts at the first value in the list (i.e. 
it is not a standard C array index based on 
zero). The value is reset to zero after any read 
list operation. | 


paflxs is set by each read field list operation to 
a non-zero number to indicate the element in a 
field pointer list at which a field read operation 
finished. A value of 1 represents the first value 
in the list (i.e. it is not a standard C array index 
based on zero). 


The lowest-level character input routine pacinp 
will look at the pakbfp variable to see if 
contains a function pointer to a background 
function which will be called continuously while 
waiting for keyboard input. 


The switch pakcln should be set during 
processing of a keyboard input background 
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routine, to indicate that the cursor has been 
moved or the highlight type changed. The field 
read routine then knows to clean up before 
processing the eventual input character. 

pamaxd The value in this variable is the maximum index 
value for the ‘DOLLAR’ numeric array 
panumd used for numeric fields. 

pamaxl The value in this variable is the maximum index 
value for the long integer numeric array panuml 
used for numeric fields. 


pamcol The maximum column number on the screen. 

pamen The x-coordinate of the screen position at the 
end of the last message processed by pamsge. 

pamhd The string used by pamsge as a heading or 
prefix for each message. 

pamln The current row number used by pamsge for 
messages. 

pammap The pammap variable is non-zero in versions of 


PANEL Plus which are running in 
memory-mapped or graphics mode. 


pamous The pamous variable is non-zero when a mouse 
is supported and available. 
pamoux/y After a mouse button depression the pamoux 


and pamouy variables contain the coordinates 
of the point at which the button was depressed. 
As soon as another key depression has been 
processed, these variables are reset to their 
default values of -1. 


pamrow The maximum row number on the screen. 


pamult A program can set the pamult value is set to -1 
to inhibit all multiple panel file operations 
(usually during application development) and to 
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force dynamically loaded screen layouts to be 
loaded from separate files. When not used in 
this way, the variable is set to zero, and changed 
to 1 automatically while the multiple panel file 
is actually open. 


panumd The array in which ‘DOLLAR’ field values are 
placed for display and returned after a read 
operation. The array element is selected for a 
currency field by using the NF extended 
attribute. 


panuml The array in which long integer field values are 
placed for display and returned after a read 
operation. The array element is selected for an 
integer field by using the NF extended attribute. 


paovth The paovth value is the ‘overlay threshhold’. 
Fields with level numbers above this value are 
displayed in overlay mode unless the mode is 
overridden with the display function control 
argument FNOVER. 


papshi/papslo These two values control the level numbers 
processed by field list and panel field 
operations. Only fields with level numbers in 
this inclusive range are processed unless the 
LNOLEV listmode argument is supplied. 


pardhi The pardhi highlight type value is used, when 
non-zero, to reset the highlighting of each field 
as it is read. 

patrid A string giving a name for the current 
screen/keyboard combination, normally not 
null-terminated. 

patrkn A user program must set patrkn to a non-zero 
value before calling pstart to enable field 
tracking, and before any call to a field list 
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display function to save the field numbers for 
the list about to be processed. The value used 
should normally be 1, since the value (minus 
one) is used as a bias for the saved field 
numbers. patrkn is reset to zero every time it 
has been used in the PANEL Plus library. 
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This chapter documents the Base Functions group in the 
PANEL Plus Library. These functions are the ones which will 
be used by the majority of applications developed using 
PANEL Plus, and handle basic control and field functions. 


The group is divided into three function areas: 
e Initialisation and termination operations 
e Field operations | 
e Dynamic load operations 


The functions are documented in logical, rather than 
alphabetic, sequence within these groups. 


Field list operations 


The functions in this group include the twelve PANEL Plus 
functions which operate on lists of fields or through panel 
control blocks. There are various common characteristics to 
these functions which will be described here. 


Each of the field list functions is passed a pointer to a null 
terminated array of field control block pointers. Such an array 
will normally be constructed by an application program in 
order to process a logical group of fields. There is no 
theoretical limit to the length of such an array. The panel field 
functions are passed a pointer to a panel control block. The 
effect is the same as using a field list function on the pointer 
array contained in the panel control block. 


Each function has an argument opmode which is the operation 
mode controlling, and passed to, the specific field operation 
which is being performed. The operation mode is therefore 
the same for all fields in the list. Examples of opmode control 
values include: whether or not to clear the field during 
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preparation; and whether or not to display help messages for 
each field during read operations. 


The list functions have an additional mode argument, the 
listmode, which controls how the field list is traversed. The 
default method of traversing a list is to examine two numeric 
variables papslo and papshi and only to process fields for 
which the ‘level number’ is greater than or equal to papslo and 
less than or equal to papshi. These numeric variables default 
to 0 and 1 respectively, but may of course be changed during 
the execution of an application program to control which levels 
are processed by list operations. 


In addition each type of function may default to process only 
input fields, only no-input fields, all fields, or no fields. These 
and other defaults may be overridden by listmode values as 
follows: 


e The value LNOLEV causes the papslo and papshi 
values to be ignored, so that the list function will 
process qualifying fields at all ‘levels’. 


e The value LDOIN causes the function to process only 
input fields. 


e The value LDONOIN causes the function to process 
only no input fields. 


e The value LDOBOTH causes the function to process 
both input and no-input fields (i.e. all fields). 


e The value LERRBRK causes the list operation to 
terminate immediately if an individual field operation 
returns an error code. Normally the list operation will 
attempt to process further fields. An example of an 
error return would be a field display operation in 
overlay mode which failed to find heap space to save 
the screen contents. 


e The value LDOEXP forces each field control block to 
be converted from internal to external format after the 
operation is complete. The value for this control is 
normally defined internally for each function which 
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may modify the field control block, and should never 
need to be specified by an application program unless 
you have modified the field primitive functions to add 
an operation which may change field control blocks. 


The above symbolic values are defined in PFCB.H, which is 
included by PANEL.H. The value DEFAULT should be 
specified if you wish to use the default Lstmode for the 
function. Values may be combined by logical or. If you wish to 
use a specific combination regularly, we recommend defining 
an new symbol, for example MYMODE = LNOLEYV | 
LERRBRK. 
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pstart — start PANEL Plus operations 


Usage: int res; 
res = pstart(); 


Source File: PUTIL.C 


Description: The pstart function is used to initialise PANEL 
Plus operations. It must be called once and 
once only at the beginning of each program. As 
supplied, the function always returns zero, since 
if it fails to operate successfully it terminates 
your program cleanly with an error message to 
stdout. The return code is provided in case you 
wish to modify the default action of the function. 


pstart calls the functions paosinit, painit, 
pascse(3) and pafunc(1). The function 
arguments used are the usual defaults. If your 
program needs other arguments for these called 
functions, you should call them individually or 
modify pstart. 


If patrkn is non-zero the pascse argument will 
have the high bit set, causing the field-tracking 
areas to be set up at the same time as screen 
save areas. 


Example: void main() 


patrkn = 1; /* enable field tracking */ 


(void) pstart(); 
(void) pfinish(); 


/* program code */ 
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pfinish — finish PANEL Plus operations 


res = pfinish(); 
Source File: PUTIL.C 


Description: The pfinish function is used to terminate 
PANEL Plus operations. It must be called once 
and once only at the end of each program. As 
supplied, the function always returns zero. The 
return code is provided in case you wish to 
modify the default action of the function. 


pfinish calls the functions pafunc(2) and 
paosterm. Note that it does not terminate the 
program and that you should either call exit 
from the application program or return from 
your main function. 


Example: void main() 


(void) pstart(); 


ss /* program code */ 
(void) pfinish(Q); 
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pelear — clear screen 


Usage: 


Source File: 


Description: 


Example: 


int res; 
PUTIL.C 


The pclear function clears the screen. It should 
only be called when there are no fields still 
displayed in overlay mode for which the ‘lose’ 
function has not been called. (As an 
alternative, the ‘unshow’ function could be used 
to remove fields displayed in overlay mode). 
The reason for this restriction is that field 
control blocks have to be tagged while fields are 
displayed in overlay mode, and if PANEL Plus 
did an internal ‘lose’ operation it could not 
guarantee to clear all these tags. 


pelear calls pafunc(3) to clear the screen and 
then returns a non-zero value if there were any 
fields remaining still displayed in overlay mode. 
This is almost always caused by faulty program 
logic, and must be corrected to avoid a gradual 
loss of both heap memory and field save 
pointers. For this reason we recommend that 
you use pclear instead of calling the low-level 


- function directly. 


if (pclear()) 


void) pfinish(); 
Se internal error\n'}; 
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pafp, palp, papp — field prepare 


Usage: #include <panel.h> 
uint opmode; 
uint listmode; 
panfcb *fcb; 
panfcb **list; 


panpcb *pcb; 

int res; 

res = a segment 

res = palp(list,opmode,listmode); 
res = papp(pcb,opmode,listmode); 


Source File: PAFP.C 


Description: The field preparation functions prepare fields 
for display. This preparation operation consists | 
of the selection and performance of one of the 
following operations: 


e If the field has a ‘toggle list’ defined with 
character validation 08 and the VL 
extended attribute, the appropriate toggle 
list entry is placed in the field. If the field 
is empty, the value corresponding to the 
alphabetic switch in the dummy first 
substring is used, but if data is already in 
the field the ‘toggle list’ is searched and the 
Switch is set to match the data item, if 
possible. See the description of the VL 
extended attribute in Chapter 6 for more 
information. 


e If the DF extended attribute is defined, the 
value (or values for a multi-line field) is 
placed in the field. This processing 
includes the recognition of the special 
‘TODAYn’ strings, described in Chapter 6, 
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Examples: 
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which cause the system date to be used as a 
default value. 


e If the NF extended attribute is defined, the 
array element number it specifies is used as 
a source value which is formatted into the 
field. In a multi-line field the specified 
array element number is the start of a range 
of elements used to initialise the field. 


e If the opmode is DEFAULT, and the field 
is an input field, it is cleared to fill 
characters. If the opmode is FPNC 
(field-prepare-no-clear) then any trailing 
blanks are changed to fill characters on 
each line of the field. IMPORTANT 
NOTE: this operation cannot be overridden 
by the listmode to apply to no-input fields, 
and is omitted if requested with pafp for a 
single no-input field. It only affects input 
fields. 


_ After finding an operation to perform in the 


above list, no other operation is carried out. 
All the functions currently always return zero. 


Valid opmode values for this function are FPNC 
and DEFAULT. 


The default listmode for the field prepare 
functions is LDOIN, that is, the default 1s to 
process input fields only. 


/* prepare the name and address field, clearing the 
data area */ 


res = pafp(&fNADR,DEFAULT); 
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/* prepare (and clear) input fields on level 4 of demo 
panel */ 


papslo = 4; 
papshi = 4; 
res = papp((panpcb *)&pDEMO,DEFAULT,DEFAULT); 


/* prepare all fields on all levels, without clearing */ 


res = papp((panpcb *)&pDEMO, 
FPNC,LNOLEV|LDOBOTH); 
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pafd, pald, papd — field display 


Usage: 


Source File: 


Description: 


#include <panel.h> 
uint opmode; 
uint listmode; 
panfcb *fcb; 
panfcb **list; 
panpcb *pcb; 
int res; 

res = Patet ceenecia 

res = pald(list,opmode,listmode); 
res = papd(pcb,opmode,listmode); 


PAFD.C 


The field display functions perform all field 
display operations. The field is displayed with 
appropriate highlighting attributes, and with a 
border if defined. Only the visible display area 
is displayed of a field with a larger data area 
than display area. The bottom right corner of 
the screen is not written to except in 
memory-mapped and graphics versions of 
PANEL Plus. If patrkn is non-zero the field 
number in a list operation will be saved in a 
special area so that the field at each position 
can be quickly determined. 


The most important factor for an application 
programmer to consider when using the field 
display functions is when to use overlay mode. 
In overlay mode the previous screen contents 
are automatically saved before the screen is 
displayed, which allows the displayed field to be 
subsequently ‘unshown’ by automatic redisplay 
of the previous contents. 


i 
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After a field has been displayed in overlay 
mode (for example a field representing a 
pop-up window) other fields (prompts and data 
entry fields) can be displayed on top of it in 
normal (non-overlay) mode. When the base 
window field is ‘unshown’ all the other fields on 
top of it will of course disappear also. This 
feature enables you to restrict the number of 
fields displayed in overlay mode, which in turn 
improves the efficiency and space requirements 
of your program. 


The first field display operation in overlay mode 
in your program will initialise the field save 
areas to allow a maximum of 16 concurrently 
displayed fields in overlay mode. You can 
increase this limit up to a maximum of 127 by 
calling the pasvin function (see Chapter 17) 
before the first field display. 


The selection of overlay mode or normal mode 
for a field is by default made by reference to 
the level number of the field. The level number 
is compared to the value of the ‘overlay 
threshhold’ variable paovth, and if the field 
level is higher than the paovth value then 
overlay mode is selected. Since paovth defaults 
to zero, the effect is that fields above level zero 
are all displayed in overlay mode if all the 
defaults are taken. This is often inappropriate, 
bearing in mind limits on the number of fields 
which can be displayed in overlay mode. 


Of course, the overlay threshhold can, and 
usually should, be changed as your program is 
running, to control which levels use overlay 
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mode. But most programs (except perhaps 
those converted from PANEL) will make use of 
the explicit selection of overlay or normal 
display mode made possible by the FOVER and 
FNOVER opmode values described below. 


The field display is controlled by the following 
opmode control values: 


e The value FRORDO causes only the border 
of the field to be displayed, if defined, and 
omits the field contents. This option is 
used to ‘frame’ an area of the screen. 


e The value FBORDD forces the display of a 
default border, if a border is defined. The 
FBORDA similarly forces the alternate 
border to be used. These two options can 
be used when an application wishes to 
alternate between the two types of border 
to indicate special program conditions. 


e The value FSPBD forces spaces to be 
displayed as border characters. This may or 
may not appear to delete the border, 
depending on whether or not the border 
highlight type is the same as the screen 
background. This option also can be used if 
you wish to clear a space round the field to 
render a graphics border. 


e The FOVER and FNOVER values force 
display in overlay mode or normal mode 
respectively. If neither value is specified 
the choice of overlay mode will depend on 
the level number of the field as described 
above. Note that even when FOVER is 
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Examples: 


specified, only fields with level numbers 
above zero can be displayed in overlay 
mode. Level zero fields are always 
displayed in normal mode. 


e The KEEPIJ value forces the display to 
start at the current position in the field. 
The default is to display the whole visible 
area of the field. 


There is no default listmode for the field display 
functions. Unless you specify LDOIN, 
LDONOIN or LDOBOTH for pald or papd, no 
fields will be displayed. 


The functions return zero after a successful 
display operation. For display in overlay mode, 
a value of 253 is returned if there is no field 
save area pointer available, and of 254 if there 
is insufficient memory to save the previous 
screen contents. patrkn is always set to zero. 


/* display a field named ‘XTRA’ in normal (not overlay) 
mode */ 


res = pafd(&fXTRA,FNOVER); 


/* display field number 27 of a panel with border only, 
as a ‘frame’ */ 


res = pafd(pDEMO-faDEMO[27],FBORDO); 


/* display no-input, then input, fields from levels 0 
and 1 only */ 


papslo = 0; 
papshi = 1; 
res = papd((panpcb *)&pDEMO,DEFAULT,LDONOIN); 
patrkn = 0; /* tracking on for input fields */ 
res = papd((panpcb *)&pDEMO,DEFAULT,LDOIN); 
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pafr, palr, papr — field read 


Usage: #include <panel.h> 


uint opmode; 
uint listmode; 
panfcb *fcb; 
panfcb **list; 
panpcb *pcb; 
int res; 

res = sexi siryahinar ng 

res = palr(list,opmode,listmode); 
res = papr(pcb,opmode,listmode); 


Source File: PAFR.C 


Description: The field read functions control all data entry 
into PANEL Plus fields, and call the 
appropriate validation functions. These 
functions do not display the field before reading 
it, unless the pardhi variable is enabled (see 
below), non-zero, and different from the field’s 
highlight type, in which case the field is 4 
displayed with highlight type pardhi before 
reading and redisplayed after reading with its 
original highlight type. 


Although the field is not always displayed by 
the read function, the functions assume that it 
has been displayed, and that the ‘current’ 
settings in the field control block, particularly 
the display area origin in the data area, match 
those on the screen. 


The field read functions all return the keystroke 

value which actually caused the read operation 

to terminate. This is in the same format as that 

returned by pagetf, with the key function A 
number in the low-order byte, with key function 
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0 indicating that a data character is in the 
higher-order byte. A special value of 0x0101 
indicates that carriage return was keyed with no 
data having been entered. The ‘list’ and ‘panel’ 
variants of this function interpret key functions 
so that an ‘up’, ‘left’ or ‘home’ key function 
moves back up the list, and others move down 
the list. These functions do not return until a 
program function or escape key is encountered 
or until the list is finished. 


The PF1 key does not normally terminate the 
list read operation, but simply moves to the next 
field. This is useful for a field with a large data 
area which would otherwise need to be scrolled 
over. The LF1BRK mode switch causes PF1 to 
behave like all the other PF keys, and terminate 
the list read. 


A ‘list’ or ‘panel’ operation can be started from 
other than the head of the list by setting the 
paflx variable to a non-zero starting value. The 
head of the list is counted as item 1 when 
setting paflx. Using this technique is not the 
same as simply heading the list further down 
the array, because that would prevent the user 
backing up to earlier fields in the array. The 
variable paflxs is set in this function and gives 
the list member at which the operation finished. 
Note that these numbers refer to the position in 
the list, not the position in the subset selected 
for reading, perhaps by restricting to specific 
levels. 


The field read is controlled by the following 
opmode control values: 
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The values FHSCRO and FVSCRO 
enable horizontal and vertical scrolling 
respectively. Without them the read only 
takes place in the displayed area of the 
field. The FHSCRO and FVSCRO values 
may be specified together. It is highly 
recommended that you use ‘full’ field 
control blocks when scrolling is enabled, 
because the ‘abbreviated’ format does not 
contain the values for the origin of the data 
area which is all that will tell you what part 
of the field is on the screen at the end of 
the read. 


The FRDHI value controls the operation of 
the read highlighting defined in pardhi. 
The default is that the pardhi value is 
ignored for an individual field read and used 
for list and panel reads. The use of the 
FRDHI value reverses these defaults. 


The FHELP value causes the help message 
specified by an HM extended attribute, if 
any, to be displayed throughout the reading 
of the field, and only the help box (HB) to 
be displayed when the help key is 
depressed. The default is that either the 
help message or, if specified, the help box is 
displayed only when the help key is used. 


e The KEEPIJ value causes the read 


operation to commence at the ‘current’ 
position of the field. The default is to start 
at the top left corner of the display area 
unless an entry mask is used. It is the 
calling program’s responsibility to ensure 


Examples: 


pafr, palr, papr — field read 


that the ‘current’ position lies within the 
display area. 


These functions are designed to process and 
report user input, so there is no explicit error 
condition returned. An error such as passing a 
field control block with incorrect dimensions or 
current position will usually quickly show itself 
by disrupting the screen display, and more 
serious application program errors such as 
invalid data pointers cannot reliably be detected 
anyway. An attempt to read a ‘window’ field 
with a data area one byte by one byte, and a 
larger screen display area, will be silently 
ignored. 


The default listmode for read operations is 
LDOIN. As you would expect, only input fields 
are normally read. 


/* read the ‘CONTACT’ field with read highlighting */ 
pardhi = 3; 
res = pafr((panfcb *)&fCONTACT,FRDHI); 


if (res = = 2) {pclear(); pfinish(); exit();} 
/* escape terminates program */ 


/* read all panel level 0 input fields, starting at field 3 */ 
papslo = papshi = 0; 

paflx = 3; 

res = papr((panpcb *)&oDEMO,DEFAULT,DEFAULT); 


a een rer 
Page 13-17 


pafuf, paluf, papuf — field unshow 


pafuf, paluf, papuf — field unshow 


Usage: 


Source File: 


Description: 


Example: 
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#include <panel.h> 
uint opmode; 

uint listmode; 

panfcb *fcb; 

panfcb **list: 

panpcb *pcb: 

int res; 

res = beluigot, ,opmode); 

res = paluf(list,opmode,listmode); 
res = papuf(pcb,opmode, listmode): 


PAFUF.C 


The field unshow functions are used to remove 
from the screen any fields which have been 
displayed in overlay mode. If you have to 
remove a heirarchy of overlapping layers of 
fields this must be done in the reverse sequence 
from that in which they were displayed. Usually 
this means matching field unshow calls to 
corresponding field display function calls. 


These functions can safely be called for, and 
with lists including, fields which have not been 
called in overlay mode. Such fields will not be 
processed, but a non-zero result may be 
returned. 


The default listmode for the unshow operation 
is LDOBOTH. 


/* unshow the field on level 5 */ 


gel 7 eee ok DEMO, 
res = papuf((panpc p 
Pees AULT,DEFAULT): 
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pafif, pallf, paplf — field lose save area 


pafif, pallf, paplf — field lose save area 


Usage: 


Source File: 


Description: 


Example: 


#include <panel.h> 
uint opmode; 
uint listmode; 
panfcb *fcb; 
panfcb **list; 
panpcb *pcb; 
int res; 

res = iu agp he 

res = pallf(list,opmode,listmode); 
res = paplf(pcb,opmode,listmode); 


PAFLF.C 


The field lose functions are used to dispose of 
the saved screen contents from ‘under’ screen 
fields which have been displayed in overlay 
mode. This function must be called prior to 
clearing the screen if there are still fields 
displayed in overlay mode which you did not 
want to bother to ‘unshow’. 


These functions can safely be called for, and 
with lists including, fields which have not been 
called in overlay mode. Such fields will not be 
processed, but a non-zero result may be 
returned. 


The default listmode for the lose operation is 
LDOBOTH. 


/* lose the save areas for all panel fields */ 


res = paplf((panpcb *)&pDEMO,DEFAULT,LNOLEV); 
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paffb, palfb, papfb — field change fill to blank 


paffb, palfb, papfb — field change fill to blank 


Usage: 


Source File: 


Description: 


Example: 
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#include <panel.h> 
uint opmode; 
uint listmode; 
panfcb *fcb; 
panfcb **list; 
panpcb *pcb; 
int res; 

res = lor bing 

res = palfb(list,opmode,listmode); 
res = papfb(pcb,opmode,listmode); 


PAFFB.C 


These functions are used to remove ‘fill’ 
characters from a field, for example the 
underscore characters which can be used to 
indicate a field length when highlighting or 
colour is not appropriate. You would normally 
use the function after the field input has been 
completed, before using or saving the field data 
in your application. 


Note that if you have been unwise enough to 
use a ‘full stop, (or ‘period’) as the fill character 
in a numeric currency field, this function will 
also change your decimal point to a blank. 


The function always returns zero. The default 
listmode is LDOIN. 


/* clean up all panel input fields */ 


res = papfb((panpcb *)&pDEMO,DEFAULT,LNOLEV); 
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paload — dynamically load screen layout 


paload — dynamically load screen layout 


Usage: 


Source File: 


Description: 


#include <panel.h> 
int ret; 
int full; 
panpcb pcb 

ret = ‘clcmeithiicls full); 


PALOAD.C 


The paload function loads a screen layout from 
disk. The pcb.pf field in the panel control block 
must have been initialised with the panel name 
to be loaded and pcb.nf must contain zero or 
the maximum number of fields to be loaded. A 
value of zero implies a limit of 255, the most 
that fit in a ‘standard’ panel control block. 
paload fills in values in the panel control block 
with the information just input and sets up field 
control blocks as required. 


Any filename extension in pcb.pf is removed 
and replaced by ‘.pnl’ for normal load 
operations. However if the pamult variable 
equals one, then paload will read the screen 
layout data from a multiple panel file which has 
been opened by pamlop and positioned by 
palook. Note that palook requires a panel 
name without file extension in the pcb.pf field. 


A single area is created for the screen data by 
dynamic memory allocation and a pointer to it 
saved at pcb.da. The data area for each field is 
followed by a single null. Note that this differs 
from the method used when code is generated 
for the panel: in that case each field line is 
followed by a null. Each field attribute area has 
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paload — dynamically load screen layout 
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the ‘nonul’ indicator set to indicate that there is 
not a null at the end of each line. 


If the ‘full’ value is non-zero then full field 
control blocks are created for each field; 
otherwise, abbreviated field control blocks are 
used. The abbreviated fcb does not include the 
field name or ‘current’ position information. 


To load a screen layout with more than 255 
fields, you will need to use a non-standard panel 
control block with a larger number of field 
control block pointers. Such panel control 
blocks can be created by defining the array size 
using the define symbol PCBFLDS before 
including the typedef in PPCB.H. If the symbol 
is not defined it defaults to 258. The array size 
should be at least two more than the field 
count, to allow for the unused ‘field zero’ and 
the null terminator at the end of the list. 


Please note: if you re-use the same panel 
control block to load another screen layout, 
remember to reset pcb.nf first. If you fail to do 
this you will never be able to increase the 
number of fields loaded. 


The paload return code has the following 
significance: 


0 Successful load 

1 Unable to open/read file 

2 Unable to read file 

253 Data area bigger than 64kb 
254 Out of memory 

255 ‘File corrupted 
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Examples: 


paload — dynamically load screen layout 


/* load the demo screen layout dynamically */ 


#include <panel.h> 
panpcb wrkfcb; 


| stropy (wrkfeb. pf,"demo'); 


wrkfcb.nf = 
res = sic hauls 1); 


/* load more than 255 fields */ 


#define PCBFLDS 1002 

#include <panel.h> /* includes PPCB.H */ 
panpcb wrkfcb; 

char *panelname; 


stro y(wrkfcb. pf, panelname); 
cb.nf = 1000; 
a = paload(&wrkfcb, 1); 
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pafree — free space used by loaded screen layout 


pafree — free space used by loaded screen layout 


Usage: 


Source File: 


Description: 


Examples: 
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#include <panel.h> 
int ret; 


panpcb pcb 
ret = nafree(Gpct): 


PALOAD.C 


pafree frees the data, field control block, and 
extended attribute areas used by a dynamically 
loaded screen layout (which will have previously 
been loaded by paload. 


Normally the return code will be zero, unless it 
is possible for the compiler library free function 
to return an error code. Unpredictable results 
will occur if the data or field control block 
pointers have been modified since the paload 
call, or if the referenced panel control block 
was never dynamically loaded. 


/* load and free the demo screen layout */ 


#include <panel.h> 
panpcb wrkicb; 


stropy(wrkich .pf,"demo"); 
res = paload (&wrkfcb, 1); 


/* process as required */ 


pafree(&wrkfcb); 
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pamlop, palook, pamicl_ — multiple panel file load operations 


pamlop, palook, pamlcl — multiple panel file load operations 


Usage: #include <panel.h> 
char *multfile, *index; 
int ret, full; 


panpcb pcb; 

ret = pamlop(multfile,index); 
ret = palook(&pcb); 

ret = pamicl(); 


Source File) PMULT.C 


Description: These functions allow screen layout details to 
be dynamically loaded from a file containing 
multiple panel descriptions. Such a file is 
created by concatenating individual panel files 
and an index for it is created by using pnlindx. 
The functions are designed so that separate 
panel files may be used during initial 
application development with the pamult 
variable set to -1: this suppresses all ‘multiple 
file’ operations, but the calls may be coded 
ready for use later in a production version. 


The pamlop function opens a file containing 
multiple panel details together with its 
corresponding index file (created with pnlindx). 
The passed file names multfile and index are 
used unchanged and file extensions have no 
special significance. The function returns zero 
to indicate success; return values of 1, 2 or 3 
indicate respectively an open failure, read 
failure or memory allocation failure. pamlop 
does nothing (and returns zero) if pamult 
contains -1; otherwise it sets pamult to a value 
of one to indicate that a multiple file is in use. 
Only one multiple file at a time may be used. 
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pamlop, palook, pamicil — multiple panel file load operations 


palook is used to determine the seek position in 
the multiple file for the start of the panel 
named in pcb.pf. The panel name should have 
no file extension. palook only functions if 
pamult contains a value of 1, i.e. if a multiple 
file is in use. The call to palook may therefore 
be placed immediately before a paload call and 
will only be effective when required. palook 
returns 1 if the name is not found in the index; 
zero indicates success or no-operation. 


pamlcl closes the current multiple file (if in 
use) and frees the space used to maintain the 
index. The pamult value is changed from 1 to 
0, effectively reverting to operation with 
separate panel files. 


palook uses a simple linked list to find the 
panel name, and always begins at the start of 
the list. If you have a large number of screen 
layouts file, and need a faster method, the 
functions in PMULT.C can be rewritten. 


Example: /* load dynamically from a multiple panel file */ 


#include <panel!l.h> 
panpcb wrkfcb; 


pamult = 0; 
res = pamlop("multfile", ‘index’); 
if (res) { /* unable to open */ } 


stro gop pf, "demo'); 
cb.nf = 

ia = alooitbbiehi: 

if (res) { /* unable to find */ } 

res = paload(&wrkfcb, 1); 


res = pamicl(); 
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SPECIAL FUNCTIONS REFERENCE 


This chapter documents the Special Functions group in the 
PANEL Plus Library. These are high-level functions which use 
fields and groups of fields in special ways. 
The group is divided into three function areas: 

e Message and Answer processing 

e Menu operations 

e Multiple field browsing 


The functions are documented in logical, rather than 
alphabetic, sequence within these groups. 
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pamsge — display message 


pamsge — display message 


Usage: 


Source File: 


Description: 


#include <panel.h> 
char *s; 
pamsge(s); 


PAMSGE.C 


The pamsge function displays the passed 
message on the current message line pamlin. If 
the string pamhd is non null then it is 
prepended to the string before display, 
separated by a colon and a space. The 
x-coordinate of the message end point is placed 
in pamen for possible use by paansw. There is 
no function return value. 


pamln should normally be initialised by your 
application program to the value defined for the 
panel in use, but may be set as required. 


The field control block used for messages and 
for paansw is pamfcb. On the first call the 
attribute table information is scanned to find a 
highlight type for use by the routine. For 
implementations where there is a highlight 
method code this will be the first highlight type 
for which the method code has the high bit set. 
Otherwise highlighting type 1 is normally 
selected. 


If the passed message string is empty then the 
message line is cleared. Passing a null pointer 
results in the previously displayed message 
being repeated. If the combined length of 
pamhd and the passed string is too long for the 
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SPECIAL FUNCTIONS REFERENCE 


Example: pamin = 4; /* move to line 4 */ 

strcpy(pamhd,"TEST MESSAGE"); 

pamsge(‘Hello, world"); 
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pamsge — display message 


screen an attempt is first made to remove any 
part of the passed string preceding the first 
occurrence of ‘[’. This effectively retains only a 
part enclosed in square brackets. If there is no 
‘’ or if the string is still too long it is truncated 
on the right. 


paansw — get answer to message 
paansw — gel answer to MeESSASE 


Usage: #include <panel.h> 
char *s; 


uint sat; 
int ret; 
ret = paansw(s,sat); 


Source File: PAMSGE.C 


Description: paansw reads a single-line field defined on the 
current message line pamln, ending at the 
x-coordinate placed in pamen by a previous call 
to pamsge. It is assumed that the passed string 
address is a pointer to the start of the area 
reserved in the previous message string to 
receive the answer. The returned text is placed 
at the passed string address, and will therefore 
overwrite a default value (or blanks) displayed 
at the end of the message by the call to pamsge. 


The pamfcb field control block is used for the 
read, and the size of its answer field is set to the 
current string length of the passed string. The 
read is carried out with the temporary fcb 
attributes also passed to the function. The 
passed attribute value can therefore be used to 
control the attributes of the read, such as 
whether upper case conversion takes place. 


paansw returns the value returned by the field 
read operation (pafr), which is in turn the same 
as that returned by pagetf. Note that the string 
length of the result string s is not changed by 
this function, and that the entered answer text 
may therefore be followed by fill blanks. 
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paansw — get answer to message 


Example: char *p, msg[80]; 
stropy (msg Ente filename (<esc> to quit) : "); 
msg[strlen(msg)]; /* set p for answer */ 
creat (msg," "); /* space for answer */ 


pamsge(msgq); /* display message */ 
ret = pemnee'p ,echo+crreq); /* get reply */ 


if ob ) {pfinish(); exit } /* user SS oaeail esc */ 
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pmenu — display menu 


pmenu — display menu 


Usage: 


Source File: 


Description: 


#include <panel.h> 
panfcb fMENU; 
panfcb fMENUHLP; 
int choice,start, nh 
choice = mimenti(&iMENU, &fMENUHLP, start, nht); 


PMENU.C 


The pmenu function displays the passed menu 
field as a pop-up field and allows the user to 
move a highlighted bar to make a selection. 
The contents of the field are first analysed to 
define the ‘tokens’ which will be highlighted. 
Tokens are defined as groups of non-blank 
characters delimited either by blank space or by 
the end of a field line. The underscore 
character (__ ) is considered part of a token but 
always displays as a space on the screen, thus 
allowing a highlighted bar to mark a group of 
words as a Single token. 


To set up a vertically moving bar in a multi-line 
menu, you must use underscore as a fill 
character, and ensure that underscores appear 
instead of blanks when there is more than one 
word on aline. This ensures that each token is 
a complete line of the field. The field will 
scroll vertically if the data area is bigger than 
the visible area. The cursor wraps from top to 
bottom and vice-versa. 


If you prefer a bar which moves horizontally 
you can arrange a group of tokens across a 
screen field. The field does not scroll 
horizontally, but a horizontal format menu can 
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pmenu — display menu 


also be set up with a multi-line field, which will 
scroll vertically if necessary. 


The space and right arrow keys move forwards 
along a line, the backspace and left arrow keys 
move back. The up and down arrow keys move 
to the last field on the previous line or the first 
field on the next. The menu wraps from end to 
end. The bar shows first on the element 
numbered with the passed starting value, if 
non-zero, and the nht argument specifies the 
highlight type to be used for the bar. 


Keying the first letter of a token also selects the 
next corresponding item starting with that 
letter. When the ‘carriage return required’ 
attribute is set for the field, the <cr> key must 
be pressed after the required token has been 
highlighted. Otherwise the keyed letter will end 
the operation. 


In versions of PANEL Plus which support a 
mouse, the mouse pointer can be positioned on 
a menu item and the left button pressed to 
select it. When the ‘carriage return required’ 
attribute is set for the field either <cr> ora 
second depression of the mouse button on the 
same token will select the highlighted item. 


If a non-null second argument is provided, it is 
taken to be a field with a multi-line data area of 
the same size as the number of menu tokens, 
and with a one-line-high screen display area. 
The appropriate line of this field is displayed in 
its screen window as the highlight bar is moved. 
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The function returns the token number 
selected, or zero if escape is keyed. It returns 
-1 if the field(s) cannot be displayed in overlay 
mode, there is insufficient memory for work 
areas, if there are too many tokens, or if the 
Starting number is incorrect. The version in the 
library is limited to 32 tokens, but can easily be 
modified if you require more. 


There are several examples of menus in the 
MENUTEST.C file and the MENUPNL.PNL 
screen layout provided. We suggest you 
experiment with the testm program (and testmi 
for the IBM Personal Computer). 
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pabrw — browse field list 


Usage: 


Source File: 


Description: 


#include <panel.h> 
panfcb **list; 


uint mode; 
int ret; 
pabrwi(list, mode); 


PABRW.C 


The pabrw function is designed to display and 
scroll through several fields ranged across the 
screen. The fields must all be the same height 
and have the same data area height. A 
highlighted bar is moved up and down the 
display, staying on the same line on all the fields 
of the list. If necessary, all the fields are 
scrolled in step. The mode parameter can be 
KEEPIJ to start the bar on a line other than the 
first, which must be the ‘current line’ of all of 
the fields in the list. 


The provided function allows ‘lines’ to be 
inserted, deleted, and edited, again 
automatically keeping all of the fields in step. 
The function is designed to be adapted if 
required before you incorporate it into your 
applications, and includes comments indicating 
how and where to refresh the field data areas 
from external data files if your application 
requires this. 


An example of the use of this function appears 
in the sample program named version. 
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PANEL-COMPATIBILITY FUNCTIONS 
REFERENCE 


This chapter documents the PANEL-Compatibility Functions 
group in the PANEL Plus Library. These are functions 
provided to enable programs using the PANEL library to be 
changed to use the PANEL Plus library with the minimum of 
effort. 


As well as making use of these calls, you may also need to 
recompile your program including the PUPC.H header file, 
which converts all upper case PANEL function and variable 
names to lower case. 


The screen-level functions in this group make use of an array 
of field control block pointers named pafpt. This array is 
normally loaded by the pausep function from the panel control 
block. For compatibilty with PANEL, this array is limited to 
255 fields (with a dummy element in position zero). For 
compatibilty with PANEL Plus it now has a null pointer at the 
end of the array so that the list processing functions can be 
used. 


You should avoid using the functions in this group for new 
applications developed with PANEL Plus. They are less 
efficient and will result in larger programs. 
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panelf — perform field operation 


panelf — perform field operation 


Usage: 


Source File: 


Description: 


#include <pni3.h> 
int ret, func; 
panfcb *fp; 
ret = panelf(func,fp); 


PANELF.C 


The panelf function is the single entry point for 
all of the PANEL field-level functions. It 
performs the function func on field fp. Names 
for the numeric values of func are defined in 
PNL3.H and are also used below. 


(Code 0) 
No action results for function code zero. 
fdispu (Code 1) 


Display the field on the screen. No highlighting 
will be carried out even if specified; however 
the border and overlay functions operate as for 
fdisp. 


fdisp (Code 2) 


Set up any highlighting for the field and then 
display the field. After displaying the field any 
necessary sequence to turn off highlighting is 
sent (for method 4 only). This function is the 
standard one used to display a field. 


If a field has a border defined, this function 
displays it. In addition it tests to see if the 
field’s overlay level exceeds the paovth 
threshhold value and if screen save is enabled: 
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panelf — perform field operation 


if so the current contents of the screen are 
saved. 


fdispa (Code 3) 


This function operates exactly as the fdisp 
function except that the alternate border is 
selected instead of the default border. Ifa 
border has been defined in the field’s extended 
attribute area then there is no difference 
between fdisp and fdispa. 


fbordd (Code 4) 


This function should only be used on a field 
already displayed with the alternate border. It 
redisplays the border only, as the default 
border. It is ineffective if the field’s extended 
attributes specify an override border. 


fborda (Code 5) 


This function should only be used on a field 
already displayed with the default border. It 
redisplays the border only, as the alternate 
border. It is ineffective if the field’s extended 
attributes specify an override border. 


funsh (Code 6) 


This function is used to ‘unshow’ an overlaying 
field, that is to redisplay the saved screen data 
which was previously ‘underneath’ it. The 
buffer containing the saved data is freed. 
IMPORTANT NOTE: if the calling program 
fails to ‘unshow’ overlapping fields in the 
reverse sequence to that in which they were 
defined, the screen contents will not be 
correctly restored. 
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flose (Code 7) 


As an alternative to ‘unshowing’ the field, the 
saved screen contents can be ‘lost’ with this 
function. The buffer area is freed, but the 
screen is not redisplayed. If the application 
decides to clear the screen while overlaid fields 
are displayed, it should call this function for 
each field first. 


freadu (Code 11) 


Read the whole field and return the PANEL 
function return code shown below. The 
highlighting is forced to type zero. 


freadh (Code 12) 


Set up any highlighting for the field and then 
read the field. If pardhi is non-zero, it will be 
taken as a highlight type for the field which is to 
be used during the field read operation. If 
pardhi is zero, the field will not be re-output by 
this function, so a previously unhighlighted field 
will not initially be highlighted unless the 
method code involves attributes which cause the 
appearance of the field to change. Characters 
will normally appear highlighted as they are 
entered. This function is the standard one used 
to read a field by PANEL. 


freads (Code 13) 


Read the field from the starting position 
specified by fi and fj. This function is normally 
used to restart reading a field from the point at 
which an escape or PF key was detected, if 


required. This function will not use 
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panelf — perform field operation 


highlighting. Note that in a field read under 
mask, the fi value is ignored and reading 
commences from the first entry position in the 
mask. 


fhigh1 (Code 21) 


Set the highlighting for the field. Not 
implemented as a panelf function in PANEL 
Plus. 


fhigh2 (Code 22) 


Complete the highlighting of the field. Not 
implemented as a panelf function in PANEL 
Plus. 


fhighc (Code 23) 


Change the highlighting of an already displayed 
field. The previous highlight type must be 
placed in paoldh. In the case of a field 
previously using attribute bytes, this function 
may need to write out blank characters to 
replace them on the screen. This function may 
also redisplay the field if this is necessary to 
change its appearance as requested. Currently, 
this function supports only highlighting methods 
1, 3 and 4. 


ferase (Code 24) 


Erase a field from the screen. This function 
tests the specified highlighting and if necessary 
will write out blank spaces to replace attribute 
bytes. The contents of the field’s data area 
need no longer be initialised to blank characters 
prior to calling this function. Currently, only 

_ fields whose highlighting uses methods 1, 3 or 4 
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pane — poe ee ee ee 


(or without any highlighting) can be erased with 
this function. 


fsetm (Code 30) 


This function will set up the mask for the field 
by reference to the characters ‘*’ currently 
found in the field’s data area (first 16 characters 
only). The ‘*’ characters indicate positions in 
which future data entry will be permitted. This 
function may be used by an application to 
dynamically change a field mask. (Alternatively 
you may assign new values to the sm structure 
element directly). If exceptionally this function 
is called for a multi-line field, only the last line 
of the field will be used to determine the mask. 


ffilm (Code 31) 


This function will fill the field with the defined 
fill character under the control of the entry - 
mask. This function must be used to clear 
masked fields in preference to function 32 
which will also erase the fixed characters in the 
field. If the field is not masked, or if the RJ, 
numeric or currency attributes are set, then this 
function is equivalent to function 32. The 
function only affects the field’s data area, and 
no data is displayed. 


ffill (Code 32) 


This function clears all of the characters in the 
field’s data area which also lie in the displayed 
screen area to the defined fill character. 


a et rte ear 


Page 15-6 PANEL-COMPATIBILITY FUNCTIONS REFERENCE 


panelf — perform field operation 


funfil (Code 33) 


This function changes any characters in the 
field’s data area to blank which were previously 
equal to the field’s defined non-blank fill 
character. WARNING: in a numeric field 
which has ‘.’ as fill character, the decimal point, 
if any, will also be cleared to blank. 


fpadf (Code 34) 


This function pads each line of the field with 
the defined fill character, replacing all blank or 
fill characters after the rightmost significant 
character. 


flnop (Code 35) 


This function performs any defined ‘line 
operation’ on each line of the field. The effect 
depends on the content of the user’s line 
validation subroutine, which is called to 
perform the operation, and on the defined line 
validation number for the field. This function is 
normally used to ensure that data pre-inserted 
into input fields is formatted with the correct 
number of decimal places and justification 
before display. If the NF extended attribute has 
been specified with a valid numeric field index 
number, this function takes the numeric 
variable and formats the value in the field data 
area. 


ffild (Code 36) 


This function clears the entire data area for the 
field to the defined fill character. If the data 
area width is one larger than the displayed 
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width, the additional byte at the end of each 
line is set to a null string terminator. 


The values returned by the panelf function after 
a read operation are as follows: 


0 Normal read, data has been entered. 

t Normal read, only <cr> was keyed 
on each line of the field. 

2 Escape function keyed at any point of 
the field. 


3 Cursor left keyed from the home 
position of the field. 

4 Cursor up keyed on the top or only line 
of the field. 

> Cursor down keyed on the bottom or 
only line of the field. 

6 Tab keyed following the last ‘word’ on 
the last line of the field. 


7 Query keyed in position one of any 
field line. 

11-24 Program function 1-14 keyed at any 
point of the field. 


A code of 254 is returned by panelf if the 
function code number is not one of those listed 
above. In addition the display and ‘unshow’ 
routines return codes as follows: 


255 Field to display overlaps screen edge 
254 No memory available to save screen 
contents under overlay field. 

254 No saved data found to redisplay on 

‘unshow’ 
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253 No more pointers free to save screen 
contents under overlay field. 

253 Field to ‘unshow’ has no valid pointer 
number. a 
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pausep — use this panel 


pausep — use this panel 


Usage: #include <pnl5.h> 


panpcb pcb; 
int ret, sfno; 
ret = pausep(&pcb, sfno); 


Source File: PANELS.C 


Description: The pausep function brings into use the 
specified panel by moving its fcb pointers into 
pafpt, the number of fields into panfl and the 
message line into pamIn. 


The sfno argument specifies a starting field 
number which will normally be zero, resulting 
in the field control blocks being loaded starting 
at field number one in pafpt. When the starting 
field number is non-zero it is used as the field 
number in pafpt at which this panel should 
start, and panfl is increased if a higher 
numbered element is used than panfl previously 
indicated. This feature allows a subsequent 
full-screen operation to operate on data from 
more than one panel. pamln is only set if the 
starting field number is non-zero. 
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panels — full-screen operation 


Usage: 


Source File: 


Description: 


#include <pni5.h> 
int ret, func; 
ret = PANELS (func); 


PANELS.C 


The panels function is the single entry point for 
all of the panel screen-level functions. It 
performs the function func on each field in 
pafpt. Names for the numeric values of func 
are defined in PNLS.H and are also used below. 


panels processes fields using paflx as an index 
for the pafpt field pointer array. paflx can be 
set by the user program before entry, and is 
always reset to zero on exit, with its final value 
saved in paflxs. 


pafpt will normally have been set up by pausep. 
panels processes fields at all ‘overlay levels’ 
lying between papslo and papshi inclusive. 


The paset array provides another method of 
controlling the fields actively used by panels. 
Any field for which the corresponding value in 
paset is non-zero will be excluded from panels 
operations. The application program is 
responsible for resetting any altered paset 
values. 


The functions provided are as follows: 
(Code 0) 


No action results for function code zero. 
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(Codes 1 - 40) 


Perform the operation defined by the 
corresponding panelf function code on all fields. 
WARNING: the selected function may not be 
appropriate for all fields. 


For panels(funsh) the fields are processed in 
reverse sequence, so that higher numbered 
levels are lifted from the screen first. This is 
not foolproof, but it is more likely to be right 
than leaving high numbered levels to the end. 


pdisp (Code 101) 


Display all the panel output fields. This 
function would normally be preceded by a call 
to pclear to clear the screen. 


pshow (Code 102) 
Display the panel ‘input’ fields. 
pzero (Code 103) 


Clear all panel input fields to their fill 
character. In a ‘mask’ field, only entry positions 
are changed. 


ppadf (Code 104) 
Pad all input fields on the right with fill. 
prjnf (Code 105) 


Performs the ‘line operation’ on each input 
field. The effect of this function depends on 
the validation code for line validation, but 
normally will right justify and format any 
numeric fields. 
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pdelf Code 106) 


Delete any fill characters from input fields, and 
replace them with blanks. 


pread (Code 107) 


Read the input fields for the panel. The 
function will evaluate the return code for each 
field and will move between fields according to 
the direction implied by the function which 
caused the field input to be terminated. The 
general linear motion is defined by the 
sequence in which the panel was written by 
panelp. An escape or PF key will cause an 
immediate return, with the return value as 
defined for panelf, and with paflxs set to the 
field number from which exit occurred. 


The panels return value is undefined except for 
the pread function. 
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ree 


pascnl — dump screen line 


Usage: #include <pnl5.h> 
uint rownumber; 
char i Nea 


strcpy(p,pascnl(rownumber)); 


Source File: PASCNL.C 


Description: The pasenl function scans through all the fields 
currently defined in pafpt to extract the data 
into a string. On the assumption that these 
fields have been displayed, the function returns 
a pointer to the contents of screen row 
rownumber. 


If the passed row number exceeds the maximum 
number defined as pamrow a line of hyphens is 
returned of the same length as the screen width. 


Fields with an overlay level outside the range om 
defined by papslo and papshi are ignored by 
pascnl. 
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pamenu — pop-up vertical menu 


Usage: 


Source File: 


Description: 


#include <pni3.h> 
panfcb *fp; 


Int ret; 
int start, menht,menhm; 
ret = pamenu(fp,start, menht,menhm); 


PAMENU.C 


pamenu displays a multi-line field and moves a 
cursor bar from line to line to allow selection by 
the user. The field is displayed in ‘overlay 
mode’ and the normal display cursor is 
suppressed, if possible, during entry. 


The menht and menhm values are used as the 
highlight type and modifier to highlight a single 
line of the field, starting at line number start. 

In this function only, lines are numbered 
starting at one in the field, but a start value of 
zero Still selects the first line. The cursor up 
and down keys are used to move the highlighted 
line up and down the field, and then the 
carriage return key selects the highlighted item. 


If a letter is keyed which matches one of the 
(upper case) characters at the start of a line in 
the field, that item is selected and the selection 
process terminates. 


Before returning to the calling program, the 
function erases the menu from the screen and 
restores the previous displayed data. pamenu 
returns -1 if the parameters were invalid, 0 if 
escape was keyed, and otherwise the selected 
line number. 
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For proper operation, the ‘screen save’ feature 
must have been enabled, and there must 
currently be two free save area pointers. 
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This chapter describes the field primitive functions which are at 
the heart of the PANEL Plus library. 


Field Control Block format 


The functions all operate on field control blocks in internal 
format, and the structure elements for this structure are 
described below. This documentation is valid for all types of 
field control block, although the item names have some 
variations between the different control block versions and the 
item sizes are also different. The only item in an external (full) 
field control block which is not in the internal field control 
block is the field name, which is an 8-byte field with no null 
terminator. The items following the two pointer values below 
are temporary areas used during field operations and validation 
functions. 


The elements in the internal field control block structure are as 
follows: 


Isx, Isy The coordinates (0 to 255) on the screen of the 
top left corner of the field display area. 

Isl, Ish The length and height (0 to 255) on the screen 
of the field display area. 

Isf The ‘fill character’ for the field. 

Iso The level number of the field, in the range 0 to 


127. While the field is actually on the screen in 
overlay mode the Iso value contains the save 
area reference number for the previous screen 
contents (0 to 127), and the high bit is set to 
identify this usage. 
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Isa 


Ism 


Iht 


Ihm 


Idw, Idh 
Icv, llv 
Ifi, 1fj 


Idi, 1dj 


Idb 
lxa 


lowfi 
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The 16 attribute bits for the field. The 
definition names for these bits appear in 
PFCB.H. 


The 16-bit screen entry mask for the field. A 
portable macro to define these bit positions 
appears in PFCB.H. 


The highlight type (0 to 15) for the field. The 
physical characteristics of each highlight type 
are mapped in the PSCxx low level screen 
module. The mapping technique differs in 
different versions of this module. 


The highlight modifier (0 to 255) for the field. 
The significance depends on the low-level 
module in use. 


The width and height (0 to 255) of the field 
data area. 


The character and line validation numbers (0 to 
255) for the field. 


The ‘current’ column and row (0 to 255) of the 
screen cursor in the field display area. 


The ‘current’ column and row (0 to 255) of the 
field display area top left corner in the field 
data area. 


A pointer to the data area for the field. 


A pointer to the extended attribute control 
block for the field. This control block consists 
of a sixteen-bit field with indicators for the 
presence of each of the possible extended 
attributes, followed by up to 16 pointers to the 
actual extended attribute strings. 


The lowest Ifi value for a field, taking into 


account the effect of any entry mask. 
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hifi The highest Ifi value for a field, taking into 
account the effect of any entry mask. 

inch The current input data character during a field 
read operation. 

dinch The current character for display during a field 
read operation. 

ninch The character to be forced as the next ‘input’ 
character during a field read operation. 

kf The current key function value last returned 

| from pagetf during a read operation. 

Iw The ‘operation mode’ supplied by the calling 
program for this operation. 

It1, 1t2 Temporary communication variables. 

ifx The index number of this field if this operation 


is part of a ‘list’ operation. Zero if an 
individual field operation. 


lhd Pointer to the head of the list in a ‘list’ 
operation. Null if an individual field operation. 
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Functions documented elsewhere 
Functions documented elsewhere 


A number of the field primitive functions are directly called by 
the corresponding individual field function operating on an 
external field control block. These functions are documented 
in chapter 13 or 17 as appropriate and the descriptions will not 
be duplicated here. The source file for each function is the 
same as the function name with the ‘i’ omitted. 
The base functions in this category are: 

e pafip - field prepare operation. 

e pafid - field display operation. 

e pafir - field read operation. 

e pafiuf - ‘unshow’ a field displayed in overlay mode. 


e pafilf - ‘lose’ a field save area after display in overlay 
mode. 


e pafifb - change fill characters in the field’s data area 
to blanks. 


The service functions in this category are: 


e pafigs - get the contents of the ‘current’ line of the 
field into a string argument. 


e pafips - put a String into the ‘current’ line of a field. 


e pafide - clear the entire data area for the field to the 
defined fill character. 


Field primitive utility functions 


Two of the field primitive functions are merely utility functions 
which do not require separate documentation other than the 
function description. 


The functions in this category are: 
e pafigp - return a pointer to the ‘current’ character in 
the field’s data area. 


e pafirn - restore null bytes at the end of each line in 
the data area, if required. 
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pafidf — fast field display 


Usage: 


Source File: 


Description: 


#include <pfi.h> 


ifcb *fp; 
int ret; 
ret = pafidf(fp); 


PAFDF.C 


pafidf does a ‘fast’ display of part or all of the 
field (normally during a read operation) without 
redisplaying the field border, if any. ‘This 
function also assumes that if highlighting 
attribute bytes are required they are already in 
place. 


The function is used to redisplay a field which 
has already been displayed with the normal 
field read function pafid, and so it does not 
need to perform all the checks carried out by 
that function. It never has to bother about 
overlay mode, because if the field has already 
been displayed you can overwrite it without 
affecting the previous screen contents. 


This function is used by a number of other field 
primitive functions and uses some special tricks 
to support their operation: 


e The field display starts from the beginning 
of the ‘current line’ (fj). Lines above this 
are not displayed. 


e Ifthe ltl temporary field is a non-zero 
value, it will be taken as a highlight type 
which will be used only for the line number 
specified in the It2 temporary field. All the 


Ee OO se aria aE LCE 
FIELD PRIMITIVE FUNCTIONS REFERENCE Page 16-5 


pafidf — fast field display 


other lines will be displayed with the 
defined highlight type for the field. 


e Normally, the routine resets default 
highlighting (type 0) on exit, but if the 
KEEPHL indicator is set in the Isw field, 
the highlighting on exit will be left as the 
field’s defined highlight type. 


The function returns zero. 
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pafidh, pafihc, pafiue — field special highlight display 


Usage: #include <pfi.h> 
ifcb *fp; 
int ret; 


ret = pate} 


ret = pafihc(fp 
ret = pafiuc(fp 


Source File: PAFDH.C, PAFHC.C 


Description: These functions use pafidf to display the field 
| using various special highlighting techniques. 


pafidh displays the whole field using the 
highlight type specified in pardhi for the 
‘current’ line only, and the defined field 
highlighting for the remainder. 


pafihe displays the ‘current’ line only of the 
field, using the highlight type specified in 
pardhi. 


pafiuc displays the ‘current’ line only of the 
field, using the normal highlighting defined for 
the field. 


All the functions return zero. 
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pafidl, pafiil — delete and insert line in data area 


Usage: #include <pfi.h> 
ifcb *fp; 


int ret; 
ret = pafidl(fp); 
ret = pafiil(fp); 


Source File: PAFDL.C 


Description: pafidl deletes the ‘current’ line of the field in 
the data area, and closes up the remainder of 
the area. The field is not redisplayed. 


pafiil inserts a line at the ‘current’ line of the 
field in the data area, and moves down the 
remainder of the area. The field is not 
redisplayed. 


Both functions return zero. 


a 
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paficf, pafifr, pafifm, pafimm — _ field data area operations 


Usage: 


Source File: 


Description: 


#include <pfi.h> 
f 


pafifm (fp); 
ret = pafimm(fp); 


PAFDC.C 


paficf clears to fill characters the portion of the 
field’s data area which corresponds to the 
displayed screen area for the field. 


pafifr replaces any trailing blanks at the end of 
each line in the field’s data area with the field’s 
defined fill character. 


pafifm replaces entry positions in a field’s entry 
mask with fill characters. 


pafimm creates a field entry mask using the 
positions of upward arrow (caret) characters in 
the data area. 


All the functions return zero. 
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pafich, pafish, pafier — field attribute bytes 


Usage: #include <pfi.h> 
ifcb *fp; 
int ret; 


ret = deh int 
ret = pafish(fp 
ret = pafier(fp); 


Source Files PAFDC.C 


Description: These functions carry out field operations which 

; need special care when highlighting is in use 
which requires attribute bytes taking a screen 
position. In most versions of PANEL Plus the 
library is supplied not supporting such 
highlighting methods, having been compiled 
without using the ATTBYTES define. These 
functions will then use a simpler method which 
may only involve redisplaying the field. 


pafich changes the highlighting of a field 
already displayed, if necessary by rewriting 
highlighting attribute bytes, but normally by 
redisplaying it. When the old highlighting type 
used attributes and the new one does not, it 
rewrites the attributes and redisplays the field. 
The old highlight type must be placed in paoldh 
to enable these cases to be handled correctly. 


pafier erases a field from the screen by writing 
blanks in its position and removing any 
highlighting attribute bytes. 


pafish highlights a field by setting highlighting 
attribute bytes at the appropriate positions. 
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All these functions attempt to handle fields 
which abut an edge of the screen, leaving no 
room for an attribute byte, but some terminals 
do not play by the rules. They all return zero. 
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pafipl, pafipd, pafipn, pafilo — numeric field processing 


Usage: 


fp,l); 
patipa df) /* DOLLAR = double */ 


pafipd(fp,d); /* DOLLAR = long */ 


pafipn(fp); 
ret = pafilo(fp); 


Source File; PLYNV.C, PAFLO.C 


Description: These functions all put numeric values into field 
data areas, taking into account the 
right-justified attribute if defined. The field is 
not displayed. All except pafilo return 1 if the 
value will not fit, and do not then change the 
data area. 


pafipl puts a numeric integer value into the 
‘current’ line of the field. 


pafipd puts a numeric currency value into the 
‘current’ line of the field. If the currency 
attribute is implemented with true floating 
point arithmetic you can override the format by 
supplying a format string as for printf. 
Otherwise the long value is converted with two 
implied decimal places. 


pafipn puts a numeric value as defined by the 
extended attributes of the field, into the 
‘current’ line of the field. The source value is 
taken from the appropriate array element, and 
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pafipl, pafipd, pafipn, pafilo — numeric field processing 


the override format is used if specified in the 
- extended attribute. 


pafilo performs the ‘line validation operation’ 
on a field (named for compatibility with 
PANEL). The effect is to call pafipn for every 


line of the field. 
non 
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This chapter documents the miscellaneous Service Functions 
group in the PANEL Plus Library. 


Some of these functions are defined in the low-level 
compiler-specific library module, but the majority are in the 
portable part of the library. 
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pabf, pabm, paix — block fill, move, and search 


pabf, pabm, paix — block fill, move, and search 


Usage: #include <panel.h> 


char *source, *dest, fill, target, test; 
uint size; 
pabf(dest, size, fill) ; 
pabm(source,dest,size); 
target = paix(source,test); 


Source File: PCMxx.C 


Description: These three functions are designed to provide a 
portable means of manipulating blocks of data 
and searching for characters in strings. Many 
compiler libraries provide these functions but 
often with different names and syntax. 


pabm moves a specified number of characters 
from one address to another, and pabf sets a 
block of bytes to a supplied value. If you use 
these functions to move and fill structures or 
arrays of other than char, you should always cast 
the pointer arguments and use the sizeof 
function in the length argument. 


paix returns a pointer to the test character in 
the null-terminated source string. If the 
character is not found, a null pointer is returned. 


Examples: /* move an abbreviated fcb to a full fcb */ 


pabf((char *)&fullfcb,sizeof(panfcb),0); /* clear dest */ 
pabm((char *)&abbrfcb, (char * aaa 


sizeof(panfcb)); /* move it */ 


{ 


i 
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/* find if a character is in the list of valid characters */ 
#include <panel.h> 


if (paix(paval,c) = = PANULD) /* it’s not valid */ 
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panimp, panexp — convert internal fcb format 


panimp, panexp — convert internal fcb format 


Usage: 


Source File: 


Description: 
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panfcb extfcb; 
lfcb intfcb; 
dors einen gt 
panexp(&extfcb, &intfcb 


PFCB.C 


The panimp function imports a normal PANEL 
Plus field control block into extended internal 
format. All external fields are converted, and 
extra fields in the internal fcb are zeroised. 


While setting up the internal field control block 
the contents of global variables prelx and prely 
are added to the coordinates of the screen field. 
This feature allows a group of fields to be offset 
by a specified amount for all PANEL Plus 
operations, since all primitive operations use 
the internal field format. 


The panexp function selects only those fields 
which can have changed from the internal 
format field control block and restores them in 
the external format field control block. The 
only fields moved are the mask, the overlay 
number, and, if the field has a ‘full’ field control 
block, the current cursor and data area origin 
position. The function does not build a 
complete external field control block. 
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pafps, pafgs — transfer string to/from field line 


pafps, pafgs — transfer string to/from field line 


Usage: panfcb fcb; 


char *source, *dest; 
int ret, max; 

ret = pafps (&fcb,source); 
pafgs (&fcb,dest,max); 


Source File: PAFPS.C, PAFGS.C 


Description: The pafps function attempts to put the passed 
source string into the current line of the field’s 
data area as defined by the cursor and data 
origin parameters in the field control block. If 
the field attributes specify right-justification, the 
string is right justified with left blank fill in the 
data area. Otherwise the data area beyond the 
string length is filled with the field’s defined fill 
character. If the passed source string is too 
long for the field data line, the function returns 
a non-zero value and no move takes place. The 
normal return value is zero. 


The pafgs function retrieves data from the 
current line of the field’s data area into the 
target string array, which is assumed to have a 
length of the max value passed. The result is 
always null terminated, and the target is 
emptied to the max length specified. To geta 
single leading character transferred from the 
data area, you must therefore specify a target 
size of 2 bytes. 
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pafde — data area clear 


pafde — data area clear 


Usage: 


Source File: 


Description: 
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The pafde function is used to clear the entire 
data area of a field to the defined fill character 
for the field. If the data area should have null 
bytes at the end of each line, they are restored 
to the correct value. 


The function always returns zero. 
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pscana — scan for field name 


pscana — scan for field name 


Usage: panfcb **list; 
int n,ret; 


char test[9]; 
ret = pscanailist,n,test); 


Source File: PSCANA.C 


Description: The pscana function is used to scan a list of 
field control block pointers to find a field with a 
name matching the passed test name. 


The passed test string is copied, converted to 
upper case, and blank filled on the right if 
required. The search is terminated after n 
items or by a null field control block pointer if 
n is zero. 


The function returns -1 if no matching name is 

found, and returns the index number in the list 
if successful. The first item in the list would be 
returned as a zero index value, but is normally 

referred to as field 1 in the list. 


The field control blocks must be ‘full’ field 
control blocks: abbreviated field control blocks 
do not contain the name. 
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prelxy — set relative field position 


prelxy —_ set relative field position 


Usage: 


Source File: 


Description: 


Example; 
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panfcb *fcb; 


prelxy(&fcb); 


PRELXY.C 


The prelxy function uses the screen x and y 
coordinates of the passed field to set the values 
of prelx and prely. The result is that all 
subsequent field operations are offset by the 
position of this field. When called with a null 
argument (PANULD), the function sets the 
offset values to zero. 


If a sub-panel screen layout is defined with 
fields in the ‘top left corner’ they can be located 
to lie on top of a ‘window’ field by using prelxy 
to set relative offsets, and the group of fields 
will always lie in the window, even if the 
window has been moved before display. 


winfld.sx = my_x_value; 
winfld.sy = my _y value; 
pafd(&winfld, FOVER); /* display window */ 
prelxy(&winfld); /* set relative position */ 
papd(&subpnil, FNOVER,LDOBOTH); /* display 
sub-panel */ 
papr(&subpni, DEFAULT,DEFAULT); /* read its input */ 
prelxy(PANULD); /* clear relative pos’n */ 
pafuf(&winfld, DEFAULT); /* unshow window */ 
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pocode — translate to old read return code 


pocode — translate to old read return code 


Usage: int new, old; | 
old = pocode(new); 


Source File: POCODE.C 


Description: The pocode function translates the new return 
code from PANEL Plus field read functions to 
the equivalent values from the old PANEL 
PANELF function. 


The new code is the same as the key value 
which was the last keystroke in the field read, 
whereas the old code was a special set of codes 
for the PANELF function. The special ‘new’ 
value 0x0101 indicates that carriage return was 
keyed before entering data into the field, and is 
translated to a 1 value. 


You may find that this function is useful to 
make the return code from paansw the same as 
it used to be, or if you use the pafr function 
simply to replace PANELF(freadh) and wish to 
retain the surrounding program logic. 
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pasvin — initialise field save areas 


pasvin — initialise field save areas 


Usage: 


Source File: 


Description: 
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int ret, n; | 
PSCxx.C 


This function is used to initialise the field save 
areas and define the maximum number of save 
areas. The function can only be called once in a 
program, and is called automatically with an 
argument of 16 when the first field is about to 
be displayed in overlay mode. The maximum 
argument value is 127. If you wish to change 
the value from the default 16, you should call 
pasvin immediately after pstart, before 
displaying any fields. 


The passed argument effectively becomes the 
maximum number of fields which may 
concurrently be displayed in overlay mode, 
because there is only this number of ‘places’ to 
save the screen contents under each field before 
it is displayed in overlay mode. 


In many cases, the default value of 16 will be 
enough, especially since if a group of fields are 
displayed in a ‘window’ then only the window 
field needs to be displayed in overlay mode. If 
you set the limit to the maximum value then any 
failure to ‘lose’ or ‘unshow’ one of your overlay 
mode fields will probably not show up during 
testing your application, but only when it is in 
production. 
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pasvin — initialise field save areas 


When designing a program which may later be 
run in graphics mode, remember that not very 
many saved pieces of screen are needed to fill 
up a large area when operating in 16-colour 
high-resolution mode. If your program really 
uses all 127 possible save areas it may not run 


in graphics mode. 
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paxasc, paxast, paxagn — scan extended attributes 


paxasc, paxast, paxagn — scan extended attributes 


Usage: 


Source File: 


Description: 


anxa *pxa; 
int n, ret, *pi 

- ret = paxast(pxa); 

ret = paxasc(pxa); ret = paxagn(n,pi); 


PXA.C 


The functions paxasce and paxast are utility 
functions which scan an extended attribute 
string and place pointers to each of the 
substrings in a pointer array named paxasp. 
The number of substrings found is returned by 
the function and also saved in paxasn. Unused 
substring pointers are set to null. 


The substring delimiter is taken to be the first 
character of the string, and the list is terminated 
by a null byte immediately following a 
delimiter. All delimiters are changed to nulls 
by the function, so that each of the substring 
pointers addresses a null terminated string. The 
paxast function operates on a temporary copy 
of the extended attribute string, but paxasc 
operates on the original. 


Either function can be called multiple times on 
the same extended attribute string, and paxast 
makes a fresh temporary copy each time. The 
lifespan of the temporary copy is until the next 
paxast call. Once you have called paxase an 
empty substring will terminate the list, because 
the second delimiter of an adjacent pair is ‘a 
null byte immediately following a delimiter’. 
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paxasc, paxast, paxagn — scan extended attributes 


The paxagn function gets a numeric value from 
the paxasp substring with the number n passed 
to the function, if that substring exists. The 
integer value is saved at the passed location. 
No change is made to the target variable if the 
substring pointer is null or if the value is zero 
or non-numeric. 


The default maximum number of substrings is 
32. To increase this value you have to 
recompile the source file with a new XASN 
value. 


SERVICE FUNCTIONS REFERENCE | Page 17-13 


LOW-LEVEL I/O FUNCTIONS REFERENCE 


This chapter documents the Low-level I/O Functions group in 
the PANEL Plus Library. 


Some of the functions in this group will have different effects 
in different versions of the PANEL Plus low-level screen and 
keyboard modules. This documentation attempts to record the 
major differences as well as the overall behaviour of th 
functions. 
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pachcl — change background colour 


pachel — change background colour 


Usage: 


Source File: 


Description: 
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#include <panel.h> 
pachcl( ... ); /* version dependent */ 


PSCxx.C 


The pachcl function changes the default settings 
for the background colour, usually by changing 
the physical characteristics associated with 
highlight type zero. Normally, the base colour 
and attributes are set during painit processing 
using highlight type zero as a model, so 
subsequent changes to highlight type zero 
attributes may not be effective in changing the 
screen background colour. The effect of calling 
this function will not show up until the next 
clear screen operation. 


The arguments will vary in number and type 
between different implementations of the 
low-level screen module. For example some 
graphics implementations may include ‘text 
font’ as one of the physical attributes, and 
others may specify screen edge (overscan area) 
colour separately from background colour. 


If you wish to use this function, which will 
probably make your application less portable, 
you should refer to the source code of the 
low-level screen module in use to determine the 
number of parameters. 
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pacinp — read input character 


pacinp — read input character 


Usage: 


Source File: 


Description: 


#include <panel.h> 
int c; 


Cc = pacinp(); 


PKBxx.C 


pacinp is the low-level function which reads a 
single input character without translation. 
pacinp may not be implemented in all versions 
of PANEL Plus, and most application programs 
requiring a keystroke input should call pagetf 
instead, which reads a complete keystroke. In 
some versions, pacinp also checks for usage of a 
mouse button. Using pacinp will cause the 
output buffer, if in use, to be flushed. 


If the variable pakbfp contains a non-null value, 
it is assumed to be a pointer to a function which 
is called continuously while waiting for 
keyboard input. Your function should return 
without undue delay, and should normally 
return a -1 value. If it returns any other value, 
the value will be truncated modulo 256 and will 
be treated as if it had arrived from the 
keyboard. This allows your background 
function to emit characters into the input 
stream. Characters will continue to be passed 
into the input stream from your function, with 
keyboard input blocked, until you again start to 
return -1 from the background function. 


In a multi-user system you should always ensure 
that the pakbfp value is null except at times 
when you specifically wish to use the 
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pacinp — read input character 


background feature. If the operating system 
cannot provide a keyboard status function, your 
background routine will never get called. When 
a ‘keyboard delay’ has been specified the 
routine will not get called between input 
characters which are part of a keyboard 
sequence. 


In the background function, if you call any 
PANEL Plus functions which move the cursor 
or changes the highlighting, you must set a 
non-zero value in pakcln to tell the field read 
function to clean up and restore the conditions 
existing before the input call. 


Page 18-4 LOW-LEVEL /O FUNCTIONS REFERENCE 


pacout — output character 


pacout — output character 


Usage: 


Source File: 


Description: 


#include <panel.h> 
int Cc; 
pacout(c); 


PSCxC 


The pacout function outputs a single character, 
after applying any highlighting specified at the 
time. ‘Applying highlighting’ may take the form 
of appending a physical attribute byte to the 
character, or preceding the character with a 
defined escape sequence, or some other 
implementation-specific procedure. In many 
cases the output will be buffered and may not 
appear immediately. 


Only the low-order byte of the passed value is 
used. 


When field tracking is on (patrkn non-zero) the 
field number or user-supplied value in paftrk is 
saved in a special screen map to enable the 
field number at a particular screen position to 
be quickly determined. 
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pacsta — keyboard status 


pacsta — keyboard status 


Usage: 


Source File: 


Description: 


#include <panel.h> 


int res; 
res = pacsta(); 


PKBxx.C 


The pacsta function returns true if a keyed 
character is available to be read. When an 
implementation cannot obtain this information 
from the operating system, the function always 
returns true. In some versions of PANEL Plus 
this function also checks for usage of a mouse 
button. 


If you write a program which loops on pacsta, 
your keyboard background function (see 
pacinp) will not get called automatically. 
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LOW-LEVEL I/O FUNCTIONS REFERENCE 


pacurs, pasbad — position cursor 
pacurs, pasbad — position cursor 


Usage: 


Source File: 


Description: 


#include <panel.h> 
int x,y; 


pacurs(x,y); 
pasbad(x,y); 


PSCxx.C 


The pacurs and pasbad functions both set a 
screen position. pacurs always positions the 
cursor, and can therefore be used before a 
low-level input function. pasbad attempts to 
make the cursor invisible, and merely sets the 
position of the next screen write operation. 


If either of the passed values is larger than the 
corresponding screen boundary, it is reduced as 
necessary. 


To turn off the cursor, for example before a call 
to pagetf to obtain a keystroke, you should 
make a call to pasbad, chosing a position which 
will leave the cursor positioned reasonably on a 
system which does not support switching off the 
cursor. 


If your program sends characters to stdout using 
normal C library functions, then these functions 
may become confused. 
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paeout, parout, pasout — output characters 
paeout, parout, pasout — output characters 
Usage: #include <panel.h> 


int Cc; 
char *s; 


paeout(c); 
parout(c); 
pasout(s); 


Source File: © PSCxx.C 


Description: The paeout and parout functions perform 
low-level character output. The former is used 
to send escape sequences to the screen and 
therefore does not store characters as part of 
the ‘screen save’ processing. 


In some implementations (e.g. when memory 
mapped output is used) the paeout function has 
no reason to be called and will therefore do 
nothing. For similar reasons parout may be 
implemented as a call to pacout. 


pasout outputs a null-terminated string using 
parout, and then flushes the output buffer, if in 
use. 
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pafunc — screen function 


pafune — screen function 


Usage: 


Source File: 


Description: 


#include <panel.h> 


int func; 
pafunc(func); 


PSCC 


The pafunc function performs a variety of 
screen functions selected by the passed 
parameter. 


Code 1 (INIT) 


For a dumb terminal, the defined initialisation 
escape sequences are sent. Ina 
memory-mapped text mode, or when using IBM 
Personal Computer ROM BIOS calls, the 
appropriate screen mode is set. In graphics 
versions this function normally switches the 
screen into graphics mode. 


Code 2 (TERM) 


For a dumb terminal, the defined termination 
escape sequences are sent. In a memory- 
mapped text mode, or when using IBM 
Personal Computer ROM BIOS calls, the initial 
screen mode is restored if it has been changed, 
which usually clears the screen also. In graphics 
versions this function normally switches the 
screen out of graphics mode. The function 
paktrm is called to terminate keyboard and 
mouse operations. 
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pafunc — screen function 


Code 3 (CLS) 


This function clears the screen to the current 
base attributes. 


_ Code 4 (EEOL) 


This function clears the current line of the 
screen to the current base attributes. PANEL 
Plus library functions only call this function 
when the cursor is positioned at the left edge of 
the screen, so it may be implemented as ‘erase 
line’ if the hardware cannot provide an ‘erase to 
end of line’ facility. 


Code 5 (BSC) 


This function should move the cursor left one 
position non destructively. It is no longer called 
by any PANEL Plus function. 


Code 6 (BELL) 


This function sends an operator alert. It is 
usually implemented as a bell or beep (variable 
in pitch and length on the IBM Personal 
Computer), but may also involve flashing the 
screen. 


Codes 7 - 10 


These functions are undefined and available for 
application program use. In some versions 
(including SCO Xenix for IBM AT) functions 7 
and 8 are used to switch the cursor between half 
size and full size to indicate that ‘insert mode’ is 
active. 
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pagetf — get keystroke 


pagetf — get keystroke 


Usage: 


Source File: 


Description: 


#include <panel.h> 
uint kf; 
uchar keyfunction, data; 


keyfunction = kf & Oxff. 


PKBxx.C 


The pagetf function gets and analyses input 
characters using pacinp and returns a coded 
‘keystroke’ value. The low order byte of the 
returned value is the PANEL Plus key function 
number defined as shown in the table below. 
When this code is zero, the high-order byte of 
the returned value is a data character. If both 
parts are zero, an undefined multiple-key 
sequence has been detected following a defined 
lead-in prefix character. 


Each PANEL Plus low-level keyboard module 
has both a key sequence and a key function 
number table. This allows multiple sets of key 
sequences to be mapped to the same PANEL 
Plus key function number. The standard set of 
key function numbers is as follows: 


Carriage Return 9 Insert Character 
Escape 10 Delete Character 
Backspace 11 Insert Line 
Cursor Left 12 Delete Line 
Cursor Right 13. ‘Tab 

Cursor Up 14 Query / Help 
Cursor Down 15 Home 

Erase EOL 16...Program Function 


CONAN P WNP 
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pagetf — get keystroke 


{ 


Higher key function numbers are used for 
additional function keys, mouse buttons, etc. as 
required. The values 251 and 252 are normally 
used to indicate single and double clicks of the 
left mouse button, when supported. 
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LOW-LEVEL I/O FUNCTIONS REFERENCE 


pagfin - get field number 


pagfin - get field number 


Usage: 


Source File: 


Description: 


Example: 


#include <panel.h> 


int fln,x,y; 
fln = pagfln(x,y); 


PSCxx.C 


The pagfin function is used to get the field 
number at a specific screen position x,y. If 
returns a non-zero value only when the PANEL 
Plus library has been compiled with the 
FIELDTRACK define set, when the pstart 
routine was called with tracking on (patrkn 
non-zero), and when a field list or panel display 
operation (pald or papd) was also called with 
patrkn non-zero. 


The field number returned is the number of the 
field in the display list, with a base of one. 

Most applications will only turn tracking on 
when displaying input fields, so that a non-zero 
value only indicates a valid entry field. 


/* mouse button depression has been detected */ 


fieldno = pagfin(pamoux,pamouy); /* get field at 
mouse pointer */ 
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painit, pakini — _ initialise 


painit, pakini — initialise 


Usage: #include <panel.h> 
char *s; 


int ret; 
ret = painit(s); 


Source File: © PSCxx.C 


Description: The painit function initialises PANEL Plus 
operations. When the low-level module uses 
the PANEL.VDU configuration file created 
using tailor, this function reads that file. If the 
file is not found in the current directory or that 
specified with the VDU environment variable, 
the function uses the TERM environment 
variable to search for a matching terminal name 
in the index of TAILOR.DAT. TAILOR.DAT 
itself is found in a default place or through the 
filename specified in the TAILOR environment 
variable. The passed string ‘s’ is an override file 
name used instead of PANEL. VDU. 


In other versions of PANEL Plus painit 
performs other initialisation operations. In 
most cases it will set up the terminal or system 
identifier patrid, together with the screen size 
values pamcol and pamrow. It may also select 
the default and alternate field border 
characters, and process environment variable 
specifiers for overriding default screen 
attributes and border colours. 


painit always calls pakini to initialise keyboard 
operations as necessary. Application programs 
do not need to call pakini directly. 
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painit, pakini —_initialise 


painit returns zero after a successful operation. 
If it returns a non-zero value there is not much 
point in continuing with your application 
program. If called more than once in a 
program the function merely returns the same 
value returned by the first call. 
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paosinit, paosterm — operating system init/term 


paosinit, paosterm — operating system init/term 


Usage: #include <panel.h> 
paosinit(); 


paosterm(); 


Source File: © PCSxx.C 


Description: These functions are provided in all versions of 
PANEL Plus, but only perform anything when 
needed. The normal use of these functions is to 
make ioctl calls in UNIX and similar operating 
systems to set the console input and output 
processing to a suitable mode at the start of the 
program and restore it afterwards. 


For portability, your application programs must 
call these functions at the very start and very 
end of operation, either directly or through 
pstart and pfinish. In a UNIX system, if your 
application program fails or terminates without 
calling paosterm the console will normally be 
left in no-echo mode and will not respond to 
carriage return at the end of acommand. To 
recover, you can often enter stty sane’J. 


In the Amiga versions of PANEL Plus, the 
paosinit function sets up the custom screen and 
window for subsequent operations. It is done in 
this function because paosinit is always called 
first, and other initialisation functions require 
the screen to be already defined. Failure to call 
paosterm will leave screen memory allocated 
after your program exits. 


ee eee re er eo 


Page 18-16 LOW-LEVEL I/O FUNCTIONS REFERENCE 


papage — IBM PC display page 


papage — JBM PC display page 


Usage: 


Source File: 


Description: 


#include <panel.h> 
int act, work; 
papage(act,work); 


PCSxx.C 


papage is only implemented in versions of 
PANEL Plus which can use IBM Personal 
Computer ROM BIOS calls or memory-mapped 
I/O, and should only be used on a system 
including an IBM Color/Graphics Adapter or 
compatible equipment. 


The function sets the ‘active display page’ and 
the ‘working page’ for use by PANEL Plus 
functions. If the passed values are different, the 
screen output functions will all operate 
‘invisibly’ until a subsequent call changes the 
active display page. The calling program must 
ensure that the passed values do not exceed 
those supported by the hardware and operating 
mode in use. 


When the active display and working page 
numbers are different, use only pacout or 
higher-level PANEL Plus routines in the non 
memory-mapped version of PANEL Plus. 
pasout and parout use the ROM BIOS teletype 
emulation which is written on the assumption 
that the values are the same. 
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pascse — Screen save enable 


pascse — Screen save enable 


Usage: #include <panel.h> 


int ret, nel; 
ret = pascse(nel); 


Source File: PSCxx.C 


Description: pascse enables screen save operations, and must 
be called, either directly or through pstart, 
before fields can be displayed in overlay mode. 
The function sets up the saving of all characters 
written to the screen, so that a request to 
‘overlay’ a screen field can first save the existing 
contents. 


The argument nel controls the number of 
elements to be saved. A value of one saves only 
the data; a value of two saves data and highlight 
type; and three saves also the highlight 
modifiers. In normal use the number of 
elements will be 3: only use 2 if you are sure 
you will never use highlight modifiers. The 
function normally allocates an area the size of 
the screen for each save element (data, type, 
modifier). 


When IBM PC ROM BIOS functions are in 
use, or in the IBM PC memory-mapped 
versions, any non-zero value for number of 
elements will be interpreted as 2, and the 
system will save the character and physical 
attribute. If the number of elements is zero a 
special mode is set up in which displayed 
characters are not saved, but extracted when 
needed directly from the display buffer using 
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pascse — Screen save enable 


ROM BIOS calls. This technique is slightly 
Slower but saves around 4k of heap space. With 
a non-zero argument value only ‘page 0’ is 
saved. 


pascse returns the number of elements actually 
set up to be saved, or -1 if insufficient memory 
is available. The returned ‘screen save element 
count’ is also placed in passec. 


When ‘screen save’ is enabled the field display 
highlighting routines ignore any highlighting 
whose method code requires attribute bytes, as 
these are not supported. 
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VALIDATION FUNCTIONS REFERENCE 


This chapter describes the operation of each type of validation 
function and provides guidelines for writing your own custom 
validation functions. 


Chapter 6 of this manual documents the supplied validation 
operations and the source code supplied to implement these is 
extensively commented. This chapter merely records the 
arguments and return values for each type of validation. 


The validation functions should not be called from a user 
application program, but only from the PANEL Plus library. 


The validation function tables 


Most of the standard functions are selected through a 
validation function table which allows specific validation 
functions to be selected using the appropriate validation 
number as an index. 


To delete any of the supplied validation functions, or to add 
custom validation functions referenced by a new validation 
number, it is necessary to modify the tables in the module 
PVTBL.C. When modifying this module you should declare 
the function name and also include it in the table initialisation. 
The pointer table can also be changed dynamically at run time. 


If it is more convenient you can create a special version of the 
code in PVTBL.C and simply include all of it in your main 
program module, where its presence will prevent the supplied 
library module from being included. Note that the PVI'BL 
module is the only PANEL Plus library module which does not 
define a function entry point. For use with VAX/VMS it 
therefore includes a dummy globaldef statement which has a 
corresponding globalref in the PAFR.C module, to ensure that 
it is automatically included by the linker. 
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pkvnn — key validation 


pkvnn — key validation 


Usage: #include <pval.h> 
int DKVXX(fp) 
ifcb *fp; 


Description: The key validation function is called when a 
keystroke value has been obtained by the field 
read function, and is passed an argument which 
is a pointer to a field control block for the 
current field. The /fi and /fj elements in the 
field control block give the current position in 
the field. 


The kf element in the field control block 
structure is the result just obtained from pagettf. 
This value can be changed during validation. 


The value returned determines how the 
keystroke is processed by the field read function. 


e Acode of 0 indicates a valid keystroke 
which will then be processed. 


e Acode of 1 indicates an invalid keystroke 
and results in a bell sound. 


e Acode of 2 indicates that the keystroke is 
to be ignored. 


e A-value of 16 added to any of the above 
results forces the calling function to restore 
the cursor position and highlighting before 
proceeding with the read operation. This 
indication must be made if your validation 
function has called other PANEL Plus field 
functions recursively for another field, or 
otherwise interfered with the screen display. 
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pkvnn — key validation 


The provided key validation function includes 
code to switch on and off insert mode 
processing, using the variables painme (insert 
mode enable) and painmo (insert mode 
currently on). 


This function also processes help messages and 
help boxes, using the special functions phlpon 
and phlpof to show and unshow the help 
message (code 1) help box (code 2) or both 
(code 3). These functions are defined in 
PHELP.C and can be modified to alter the way 
in which help is displayed, for example to 
display the help box legend ‘Help’ in a different 
language. 
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pevnn — character validation 


pewin — character validation 


Usage: #include <pval.h> 


int pevXX (fp 
b *fp; 


Description: The character validation function is called when 
an input data character has been identified, and 
is passed an argument which is a pointer to a 
field control block for the current field. The /ft 
and /fj elements in the field control block give 
the current position in the field. 


The inch element in the field control block 
structure is the character which has just been 
input, and which will be saved in the field data 
area when the function returns. The dinch 
value is initially a copy of inch, and will be the 
character displayed when the function returns. 
Saving a non-zero value in ninch before return 
will force this to be used as the next ‘input’ data 
character instead of the next keyed character. 


The value returned by the function determines 
how the character is processed by the field read 
function. 


e Acode of 0 indicates a valid character 
which will be saved in the field data area 
and normally displayed also. 


e Acode of 1 indicates an invalid character 
and results in a bell sound. 


e Acode of 2 indicates that the character is 
to be totally ignored. 
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pevnn — character validation 


e Acode of 3 indicates that the character is 
to be ignored but that the keystroke is not 
to be ignored, so that for example if the 
field line was filled the processing for 
end-of-line will still be carried out. 


e A-value of 16 added to any of the above 
results forces the calling function to restore 
the cursor position and highlighting before 
proceeding with the read operation. This 
indication must be made if your validation 
function has called other PANEL Plus field 
functions recursively for another field, or 
otherwise interfered with the screen display. 
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plvnn — line validation 


Usage: #include <pval.h> 
int plvXX(fp) 


ifcb *fp; 


Description: The line validation function is called from the 
field read routine as soon as an input line has 
been completed, or the cursor has been moved 
up or down from it. The function is passed an 
argument which is a pointer to a field control 
block for the current field. The kf element in 
the field control block contains the keystroke 
which caused the line to be considered 
complete. 


The value returned by the function determines 
how the line is processed by the field read 
function. 


e Acode of 0 indicates a valid line which has 
not been altered in the validation function. 


e Acode of 1 indicates an valid line for which 
the field data area has been modified in the 
function, and now needs to be redisplayed. 


e Acode of 2 indicates an invalid line which 
has not been altered in the validation 
function. It results in a bell sound. 


e Acode of 3 indicates an invalid line for 
which the field data area has been modified 
in the function and needs to be redisplayed 
before it is rejected. It results in a bell 
sound. 
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plvnn — line validation 


e A value of 16 added to any of the above 
results forces the calling function to restore 
the cursor position and highlighting before 
proceeding with the read operation. This 
indication must be made if your validation 
function has called other PANEL Plus field 
functions recursively for another field, or 
otherwise interfered with the screen display. 
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pivin — field validation 


Usage: #include <pval.h> 
int pfvXX(fp) 


ifcb *fp; 


Description: ‘The field validation function is called from the 
field list read routine after the processing for 
the field is complete. The description ‘field 
validation’ is a little misleading as it is too late 
to do much about the validity of the field. The 
function is passed an argument which is a 
pointer to a field control block for the current 
field. The kf element in the field control block 
contains the keystroke which caused the field to 
be considered complete. 


The value returned by the function, if non-zero, 
is the field number in the field list of the next 
field you wish to process. If the number is zero 
the processing continues in the direction 
determined by the terminating keystroke. 


The normal use of this validation exit is to 
determine the field number of the selected field 
when the key function number indicates a 
mouse button selection. 
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MODIFYING PANEL PLUS LOW-LEVEL 
MODULES 


PANEL Plus is delivered with a range of low-level screen, 
keyboard, and compiler-specific modules which should be the 
only modules you need to modify when porting your 
applications to a new environment. 


This chapter describes how to: 

e Modify a compiler-specific module and the PNLI.H 
file to support a different compiler in an 
already-supported operating system, or to support a 
new operating system. 

e Change the table-driven keyboard module to include 
different pre-defined keys or allow multiple keys to be 
defined for the same function. 

e Support a new graphics function library. 

e Support additional mouse selection buttons. 

There are a growing number of low-level support modules, and 
the number will continue to grow during the currency of this 
manual. The files SCREEN.DOC and KEYBOARD.DOC list 
the currently available modules. Detailed documentation of 
the facilities available in each environment will be found in the 
source module itself. 
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The PNLI.H header file 


If you wish to create a version of the PANEL Plus library to 
interface with a new compiler or operating system, one of the 
most critical tasks is to create a PNLI.H ‘interface header file’ 
which correctly specifies the environment in which you will be 
operating. 


The best place to start is with one of the provided PNLLH files 
which best matches your target environment. You will also 
need to peruse the list of defines in Chapter 12 and select any 
which apply and which need to be included in PNLLH to affect 
all modules. 


It is impossible to be more specific about PNLLH. If all C 
compilers and operating systems were the same it would not be 
needed. If you do not enjoy experimenting with these 
portability issues you could always switch your application 
development to COBOL. 


The Compiler-specific module 


This module includes hopefully all low-level code which needs 
to be changed for a particular compiler or operating system. 
The areas covered in this module are: 


e Operating system initialisation and termination 
functions, not normally required for DOS, but essential 
if the operating system defaults to echoing all key 
input to a program, or to requiring a ‘return’ or 
‘newline’ before passing keyed data to a program. 

e Lowest-level raw character input and output. For 
DOS compilers, the names of the functions used to 
invoke DOS functions or software interrupts normally 
vary from compiler library to compiler library. 


e Block move and fill operations. We use provided 
library functions if available, as these are often coded 
in Assembler for speed. 


e Obtaining the system date. 
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Once again the best approach is to take an existing 
compiler-specific module which best fits your target 
environment and modify it as necessary. We have so far found 
only one compiler which requires assembler code in this area: 
the Microsoft Compiler int&6 function does not return the zero 
flag and so cannot be used for DOS function 6. In all other 
cases the compiler-specific module is written entirely in C. 


IBM Personal Computer memory-mapped I/O 


If you recompile the PANEL Plus library with a new DOS C 
compiler you must provide an assembler module to perform 
reads and writes in the video regen buffer, and Microsoft 
Mouse calls if required. One of the provided assembler 
modules should be used as a base. The functions could 
probably be written in C, but only if you are prepared to put up 
with ‘snow’ on a standard CGA display, and slightly reduced 
performance. The provided assembler modules make the 
special calls which are required for MS-Windows and Topview 
to obtain and refresh a ‘virtual’ memory buffer. 


Table-driven Keyboard Operations 


The keyboard tables in the provided table-driven keyboard 
modules can be changed either in the source code or 
dynamically to support different key sequences. 


There are two tables: the pakeyt table contains the values to 
be recognized and the pakbtt table translates an entry number 
in the first table to a PANEL Plus key function number. 


The pakeyt table contains word values in some versions and 
character string pointers in others. For the latter, a generalised 
search routine is provided which handles strings of different 
lengths in a way which minimises the number of string 
comparisons. You need to set a define LARGEST SIZE to 
the maximum length of an input sequence for a key. 


The pakbtt table is provided to make it easy to have multiple 
key sequences which perform the same PANEL Plus function. 
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Graphics low-level modules 


To interface PANEL Plus with a new graphics library you 
should first print out for study each of the provided graphics 
low-level modules. 


The functions which your module needs to provide are as 
follows: 


Initialisation. This function may be simply a matter of 
calling a single graphics library function, or it may 
involve several pages of code to determine workstation 
characteristics, open windows, and select fonts and 
colours. All of the provided modules assume that 
PANEL Plus will do this initialisation, but you may be 
able to simplify things if your application already does 
the initialisation and you only require PANEL Plus to 
operate in your own graphics environment. In that 
case your initialisation routine only needs to assign 
values to the PANEL Plus variables which are used in 
subsequent functions. 


Display attributes. Depending on the capabilities of 
the graphics library, the code should support 
foreground and background colours and patterns, and 
text fonts, selectable in preset combinations through 
the PANEL Plus highlight type. 


Initialisation overides. Most of the supplied functions 
allow modes and colours to be specified at run-time, 
usually by using the PAMODE and PAIATT 
environment variables. The hexconv function 
processes hexadecimal strings from these environment 
variables. 


Cursor functions. Some libraries provide text cursor 
functions, and for others we have to build a cursor, 
usually by inverting a character-sized rectangle on the 
screen. 


Text output functions. The buffer output function is 
called whenever the text cursor is positioned or the 
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output attributes change and must write a text string 
with the appropriate attributes and position. Currently 
only fixed-width characters are supported. 


e Area Save and restore. The palift function must be 
coded to save an arbitrary rectangular area of the 
screen, and the pardsp function must redisplay a saved 
area. In pasvif you must calculate the size of the area 
required and allocate memory for it. If the library 
does not provide a device-independent way of 
calculating the size, this may involve some tedious 
calculations. 


e Box-drawing. If your graphics font includes line-draw 
characters, you may be able to define a standard 
border and use the normal PANEL Plus field display 
routines to paint it as text. Otherwise, there are two 
methods of drawing ‘boxes’. In the first, the padrbb 
function draws an empty box with a suitable border, 
incorporating the ‘legend’ if possible, and then the 
normal display routine fills in the box text. In the 
second, the ‘box’ edge and corner values are all 
defined as blanks and displayed by the normal display 
routine, and then the padrba function draws a line or 
lines all round the box in this ‘blank’ border space, 
hopefully avoiding overwriting any displayed legend. 
You should choose the method most appropriate for 
the capabilities of your graphics library. 


The provided graphics library interface modules generally 
presuppose a fairly standard 80 by 25 graphics text display area. 
Supporting only fixed-width fonts minimises processing 
overhead and ensures that all area move operations are aligned 
on byte boundaries. All of the assumptions could be changed 
by modifying the source code but investigation may persuade 
you that the compromise we have chosen is a wise one. 
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Mouse Operations 


The built-in mouse functions in PKB02.C support the 
Microsoft mouse and allow selection with the left mouse 
button, which is returned as a dummy ‘function key’ with 
number 251. It should not be difficult to modify the code for 
other mice or to support other button combinations. The 
PANEL Plus field and screen functions support positioning 
within fields and field selection using the mouse button. 


We took the decision not to support mouse ‘dragging’ because 
it considerably complicates the code. There are few 
application operations which can make use of this function, 
with the exception of drop-down menu processing, and most 
graphics environments in which drop-down menus are the 
norm already include extensive menu functions which support 
mouse selection. If you do include code in the keyboard 
module to follow mouse movement, remember to turn it off in 
the keyboard termination function paktrm. 


For some graphics environments which also support locator 
devices we provide a special keyboard module which includes 
these functions. 
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This chapter describes the use of the tailor program to 
maintain the TAILOR.DAT terminals file and to select a 
PANEL.VDU file for the hardware in use. Then the 
parameter set format and content are described, as well as the 
use of the keyboard and vdugenc utilities. 


Note that the contents of this chapter are only relevant when 
you are using a PANEL Plus library with the PSC01 or PKBO1 
modules. Other versions of the low-level modules do not use 
this tailoring system. In particular, you can ignore the 
references in this chapter to the IBM Personal Computer if you 
will only be using the memory-mapped modes described in 
Chapter 22, or the graphics versions described in chapter 20. 


The tailor program 


tailor performs visual display and keyboard tailoring functions. 
It includes a great deal of explanatory material which will be 
displayed to help you make the necessary entries. This 
description is therefore designed merely to give a general idea 
of its capabilities, and to help you plan what you are going to 
do with it. 


The source code for tailor is supplied, so that you can 
configure your applications for different terminals on a system 
to which you may port your PANEL Plus applications. 


tailor can be operated without any external files other than 
TAILOR.MSG, in which case all you can do with it is create 
PANEL.VDU which contains the details of the current active 
terminal. Normally, however, you will use tailor in conjunction 
with the TAILOR.DAT file which holds a number of sets of 
terminal definitions. You can then pick one of the predefined 
parameter sets and store it as PANEL.VDU to make it ‘active’, 
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edit or modify it, and then save it again in TAILOR.DAT if you 
wish. 


The most important aspect of the tailor operating environment 
is the screen and keyboard from which you run the tailor 
program. This need not be the target system for the current 
tailoring operation. If it is not, you will not be able to use the 
interactive keyboard specification option, but you can define all 
the keyboard codes by working out yourself how to recognize 
them. 


The other thing you may not be able to do when tailoring for a 
different system or terminal is to use the facilities provided to 
test each output code. tailor does not prevent you from doing 
this, because you may know that the codes are the same on 
your terminal. Be aware, however, that another system’s ‘clear 
screen’ code might well turn off the keyboard on your own. 


You will find that tailor will ask you whether the basic screen 
functions have been defined correctly for your terminal. If this 
is the case you will be spared the undignified sight of questions 
scrolling up from the bottom of the screen. 


Using the tailor program 


tailor can do three things: it can pick terminal details from 
those in TAILOR.DAT, it can save terminal details in 
TAILOR.DAT, and it can edit the terminal details. The 
‘active’ terminal details are always held as PANEL.VDU and 
you will be asked whether you wish to update this file by 
‘saving’ the changes after each editing operation. tailor 
determines which of these files are present and adapts its 
menus automatically so that you are not presented with 
impossible options. 


Editing terminal details 


The main editing menu allows you to choose the following 
things to edit: 
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Terminal ID 

Delay parameters 

Basic Screen Output Functions 

Cursor Positioning and Screen Size 
Highlighting 

Keyboard Codes (Interactive) 
Keyboard Codes (for another terminal) 


If you are starting from scratch it is a good plan to work down 
this menu from the top, because this way you will be able to 
test each function as you define it. Some of the functions 
require that the preceding items have been correctly specified. 


For each section, there is space to enter a comment about what 
has been defined, which may be helpful if you cannot 
remember later what the codes were for. For the highlighting 
and keyboard codes there is a separate comment field for each 
element. 


Tailor code input conventions 


tailor always displays existing codes as a sequence of decimal 
numbers, but when it comes to entering a new sequence the 
only input convention is to enter the values any way you like. 
Just about the only reasonable entry method that tailor doesn’t 
recognize is octal. 


A code sequence is entered element by element, and since 
most sequences are fairly short, tailor requires that you enter 
the whole sequence even to change one already defined. If you 
make a mistake you can enter ‘B’ followed by carriage return to 
back up the list. For really bad mistakes, an ‘A’ code will 
abandon entry without changing the existing codes. 


If you enter a numeric value, it is assumed to be decimal, 
unless it is followed immediately by an ‘H’ in which case it is 
treated as hexadecimal. You can also use any of the standard 
ASCII codes, if you can remember them, such as SOH and 
NAK and things like that. When the code to be entered is a 
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letter (for example in a sequence such as ‘escape - K’), then 
you can press the space bar to indicate ‘use the following 
character’ and then just type capital ‘K’. Easier than looking 
up decimal 75 or hexadecimal 4B. Finally, ‘control’ characters 
can be entered by pressing the ‘~*~’ key, and then typing the 
appropriate letter or symbol. 


As an example, there are five different ways in which you can 
place an ‘escape’ character in an output sequence: 


1. Enter ‘27’ followed by carriage return 
2. Enter ‘1BH’ followed by carriage return 
3. Enter ‘ESC’ followed by carriage return 
4. Enter ‘*’ followed by ‘[’ 

5. Enter space, then press the escape key 


In addition to all of the above, there are special alphabetic 
codes you can enter: for example a ‘D’ inserts a software delay 
- into the sequence, of a length specified by the output delay 
parameter, and ‘X’ and ‘Y’, each followed by carriage return, 
can be used in a positioning sequence to indicate ‘the 
coordinate value goes here and it’s a binary value’. Details of 
the alphabetic codes are given below. 


Interactive keyboard editing 


Although it is fully explained in the tailor program, it is worth 
noting here that you specify your keyboard codes by pressing 
the actual key when asked to. tailor uses a full-screen display 
for this process and shows the code read as soon as it has been 
entered. When you have finished your entries and come to 
save the table, tailor works out the best way of recognizing 
each code. If it displays ‘SINGLE’ or ‘MULTIPLE’ in the 
status column, it has successfully determined its recognition 
strategy: if not, the offending codes will be marked as 
duplicates or as having no unique distinguishing features, and 
you will have to try again. 
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In rare cases, you will find that the status column contains a 
‘NOT VALID’ message when the keyboard table is first 
displayed. This usually means that you have unsuccessfully 
defined the keyboard codes with the non-interactive option, 
perhaps by specifying a pair of characters of which the first has 
not been defined as a prefix. You can clear this error by 
respecifying the key. A ‘null’ entry (CTL-@) ‘undefines’ a 
function. 


The interactive keyboard editing procedure does not currently 
permit more than five function keys to be defined. If you need 
to define more than this, and if the keyboard generates no 
more than two characters from any key depression, you may 
extend the ‘keyboard recognition table’ into the ‘ignore table’ 
by entering the character pairs generated by each function key 
using the ‘K’ option of tailor editing. The list of character 
pairs has to be terminated with a 255 value (which is displayed 
as ‘D’) to indicate that this feature has been used, and a 
maximum of nine extra function keys can be defined in this 
way. For further information, see the Tailor Interface 
specification details below. 


Currently the interactive keyboard editing feature requires a 
screen at least 80 by 24 to operate. If your screen is less than 
this size, you will have to use the non-interactive keyboard 
specification option (or buy a bigger screen). 


Special Alphabetic Entry Codes 


In any sequence a code of ‘D’ will specify that a delay is to be 
introduced at that point. The length of the time delay is 
specified by the first delay parameter. 


For cursor addressing and direct screen buffer addressing the 
following alphabetic entries in a code sequence are used to 
indicate the position of a row or column number in a sequence. 
Immediately following the letter must be a value denoting the 
offset to be applied to the coordinate. As an example, the 
common positioning sequence of ‘Escape Equals’ followed by 
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row and column coordinates offset by 20h is entered to tailor 
as a six-element sequence as follows: 


bow ce of Of A oe 


The full range of alphabetic codes for screen addressing is as 
follows: 


Column value, single byte binary 
Row value, single byte binary 
Column value, variable length ASCII 
Row value, variable length ASCII 
Column value, two-byte ASCII 

Row value, two-byte ASCII 

Column value, three-byte ASCII 
Row value, three-byte ASCII 
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Another set of alphabetic codes are used in attribute ‘on’ 
sequences as follows: 

e A ‘P’ sends the remainder of the sequence (max 8 
characters) as a prefix for each character to be 
highlighted. 

e An ‘N’ causes the next following byte to be used as an 
increment for each character output (modulo 256). 
This feature can be used to convert alphabetic to 
‘control’ characters for graphics purposes. 

e An ‘S’ sets the high bit of each character output. 

e An ‘M’ causes the ‘highlight modifier’ to be used at 
this point in the sequence by adding its value to the 
next character of the sequence. 

The TAILOR.DAT file 


The tailoring data file consists of an index block followed by a 
data block for each set of PANEL.VDU information. Each 
block is 1024 bytes long. The index block contains a 10-byte 
reference field, a single byte value of the number of data 
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blocks, a filler byte, and up to 50 ten-byte index entries 
containing a copy of the termid field from the data block. The 
second half of the index block is unused. 


Each data block is formatted as described below for 
PANEL. VDU. 


The PANEL.VDU screen and keyboard parameter file 


The PANEL.VDU information has seven sections as follows: 


Identification 

Screen Functions 

Visual Attributes 

Screen Size and Cursor Position 
Delay Parameters 

Keyboard Functions 

Comments 


A formal record layout of the record appears in the PSC01.C 
source file. 


Three sections of the record, those for VDU Functions, 
Attribute Definition, and Cursor Addressing, contain control 
sequences sent to the VDU to perform various functions. In 
each case the actual control sequences are held in a data area 
for each section, and the sequences for each function are 
defined by means of a length and address in the data area. 
This allows the maximum flexibility in the lengths of the 
various control sequences: the PANEL Plus interface does not 
specify a maximum length for individual control sequences, 
only for the total of each section. In cases when identical 
control sequences are required (e.g. ‘attribute off for some 
screens) space is only taken up for a single definition in the 
data area, with each function automatically defined as the same 
length and address. 


In the record data areas, any characters other than Oxff are 
treated as data characters and transmitted to the terminal. Oxft 
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is normally a signal for a delay sequence to be initiated, and is 
also used to signal special functions in the cursor addressing 
and ‘attribute on’ sequences. These features are described 
below. 


The ‘comment’ areas of the record have a separate section for 
each part of the record. It is particularly important for the 
comment fields describing the keyboard functions to be set up 
correctly, because keyboard can be used to display the key 
assignments described in these fields to an operator. The first 
comment field can also be displayed by the tailor program to 
assist in selecting a parameter set, and should contain a fuller 
description of the configuration than is allowed by the 
ten-character terminal name. 


Terminal Identification Section 


A ten-character field is provided to identify the system or 
terminal to which the parameters apply. This field is displayed 
by some of the programs in the PANEL Plus system and is also 
made available for access by user programs if required. 


Screen Functions Section 


Up to ten screen functions may be defined, of which six are 
used in the PANEL Plus system. The other four are available 
for special purposes in user-written programs. A data area of 
128 characters is available for specifying the control sequences. 


The details of the use of the functions are as follows: 
e INIT (VDU Initialisation) 
This control sequence should be sent to the terminal at 
the start of every program. It is normally used for 
some or all of the following functions: 


Ensuring that the VDU is operating in the correct 
mode. 

Selecting the correct character set 

Setting the display mode for the cursor 
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Setting default video attributes or background colour 
Programming any programmable function keys 
Setting the screen width or character size 


e TERM (VDU Termination) 


This sequence is used to deprogram any terminal 
settings made in the initialisation process which are 
not the standard ones for the installation. As an 
example one might wish to reset the screen width to its 
usual value, say 80 columns, after an application which 
required a 132 column screen. 


The PANEL Plus system programs will attempt to 
send this sequence before terminating, although it may 
not be possible in the case of certain abnormal 
program exit conditions. It is the responsibility of a 
user program to call for this function sequence to be 
transmitted before terminating. 


It is recommended that the termination sequence 
should not include codes which cause the screen to be 
cleared. In many programs a fatal error is signalled by 
an error message prior to termination, and this will not 
be visible to the end-user if the subsequent 
termination sequence clears the screen. 

e CLS (Clear Screen) 
This sequence should clear the screen and leave the 
cursor in the top left hand corner. On a terminal 
which uses attribute bytes for highlighting, it is 
important that they are all cleared by this code. 

e EEOL (Erase to end of line) 
This sequence should preferably clear the line from 
the current cursor position, although it is acceptable 
for the whole line of the cursor to be cleared since the 
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PANEL Plus system only uses this function after 
positioning the cursor at the left side of the screen. If 
this function is not defined (i.e. length of the sequence 
is zero) then the PANEL Plus system will output a 
suitable number of spaces to clear the line. 


e BSC (Backspace Cursor) 


This code sequence should be defined as the most 
direct sequence which will move the cursor left one 
position. The PANEL Plus system will never call this 
function when the cursor is in the leftmost column of 
the screen, so its effect there is immaterial. 


Note that there need be no connexion between the 
code defined for this function and that generated by 
the key which is defined to be the ‘cursor left’ key. 


e BELL (Bell or screen flash) 


This function will be defined on most terminals as 
0x07, which will cause the bell or beeper to sound. If, 
exceptionally, the terminal has no bell or beeper, it is 
sometimes possible to specify that the whole screen 
should flash by programming for ‘reverse video’, 
‘delay’, and then ‘normal video’. The PANEL Plus 
system normally uses this function to indicate either an 
error or that operator intervention is required. 


e SPR1 - SPR4 (Spare Functions) 


The spare function positions are provided to allow 
user-written programs to make use of screen features 
other than those used by the PANEL Plus system. 
They can be used in the development of applications 
which are to be used on a range of terminals which 
have different codes to perform the same functions. 
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Delay Parameters Section 


There are two delay parameters which can be specified to the 
PANEL Plus system, each by means of a single-byte value from 
0-255. 

e DELA (1) (Screen Output Delay) 


This value controls the amount of delay introduced by 
the Oxff character in output function sequences. The 
delay method is implementation-dependent. As a 
guide, a value of 10 in the screen output delay should 
cause a delay of about one character. This means that 
a value of 100 would introduce a delay of about ten 
characters for each ‘delay’ character in the output 
string. 

e DELA (2) (Keyboard Input Delay) 


This value controls the wait time which is introduced 
after detecting the first character of a multi-code key 
sequence. Its principal use is to allow the use of a 
single ‘escape’ key on keyboards which generate codes 
prefixed by the escape character for other functions 
such as ‘cursor arrows’. After detecting the prefix 
character, the program waits for a time specified by 
this parameter. If a code is detected from the 
keyboard during this period, then it is assumed to be 
part of a multi-key sequence and tested as such to 
determine if it is a valid sequence; if not, the prefix 
character is assumed to be a single code, and is tested 
to determine if that code is defined as a keyboard 
function. 


The correct value should be determined by experiment 
in systems supporting this feature. As a guide, a value 
of 20 is recommended for a SMhz 8086 operating at 
baud rates from 1200 to 9600, but a value of 4 or less 
may be sufficient for a system with integrated screen 


Visual Attribute Section 


and keyboard. Too large a value will cause a 
noticeable sluggishness in responding to a single keyed 
prefix character, and will result in the system “beeping’ 
on fast keying as a result of multiple keystrokes being 
taken as part of one sequence. Too small a value will 
result in cursor movement or other function commands 
being interpreted as the single defined prefix. These 
problems can only affect keyboards which generate 
multiple key sequences. 


If this value is set at zero, a different method of 
detecting and identifying input sequences is used. 
Characters are analysed as they come in, and first 
examined to see if a defined prefix is present. If so, 
characters are read until a sequence is either 
recognized or rejected. This method is the 
recommended one for use if the system codes allow it, 
but it does mean that a single ‘escape’ or other 
character which is also defined as a prefix cannot be 
used as a ‘single’ function key because it always causes 
a second ‘read’ from the console. 


If no keyboard status is available from the operating 
system the PANEL Plus subroutines will force the 
second delay parameter to zero even if another value 
has been entered. 


Visual Attribute Section 


This section of the VDU information file allows a wide variety 
of highlighting methods to be specified. Up to sixteen different 
highlight types or colours can be specified, and there are 
currently four different ‘highlight method’ codes. The code 
sequences for all the on and off sequences must fit within the 
space of 128 bytes. 


It is recommended that highlight types 1 and 2 are reserved for 
simple screen functions such as inverse video, which are 
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Visual Attribute Section 


available on many terminals. It helps transportability if the 
more exotic functions are kept to the higher numbered 
highlight types. | 

e METH (0-15) (Highlight Method) 


It is necessary to specify a highlighting method for 
each of up to sixteen highlight types which are 
available. Method code zero indicates that the 
corresponding highlight type is not defined. The other 
codes have meanings as follows: 


aS 


Attribute bytes are needed which take up a position 
on the screen preceding and following the data 
field. The visual attributes of characters already 

on the screen between the attribute bytes are 
changed when the attribute sequences are written. 


: Attribute bytes are needed which can be overlaid 


by data characters and which take effect from the 
character position following the attribute byte. 


: Attribute bytes are needed which can be overlaid 


by data characters and which take effect from the 
character position of the attribute byte. 


: A control sequence is sent to the screen to turn ‘on’ 


a particular set of attributes for characters 
subsequently transmitted to the screen, followed 
by a control sequence which turns ‘off that set of 
attributes and restores the default attributes. No 
screen positions are allocated for the control 
sequences. 


: Special code for border definition in which the ‘on’ 


sequence defines the default border and the ‘off 
sequence defines an alternate border. 
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In conjunction with any of the above codes (normally 
with method 4) a set of two-byte codes may be placed 
in the ‘on’ sequence, each of which starts with the 
character Oxff. When followed by a zero value, this 
code introduces a delay. A following code of 1 to 4 
corresponds to the code letters P, N, S, and M 
respectively. 


The ‘method’ selected for each highlight type controls 
the use of the ‘on’ and ‘off’ sequences which are 
described below. 


For the panelp screen editor program, it is 
recommended that one highlight type (e.g. inverse 
video) is specified for use to highlight messages and to 
indicate ‘selected’ fields. This is done by setting the 
high bit of the method code for one of the highlight 
types (e.g. enter 132 instead of 4). 


Currently, panelp only supports the use of methods 3 
and 4 for this purpose. This message line highlight 
specification will also be used by default in developed 
application programs. 


Highlight method 1 can also be used to output 
single-byte visible characters instead of control 
sequences. For example, the ‘on’ sequence can be set 
to ‘[’ and the ‘off to ‘)’ which will cause fields to be 
delimited with these characters. 


e ONO - ONF, OFFO - OFFF (Highlight On and Off) 


The sixteen highlight sequences are numbered 0 to F, 
using hexadecimal notation. In general, the ‘on’ 
sequence precedes the field and the ‘off sequence 
follows the field. 


For methods one to three, the PANEL Plus system 
writes the ‘off? attribute byte first, following the field, 
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Cursor and Screen Size Section 


and then the ‘on’ attribute preceding the field. This 
technique helps to avoid the remainder of the screen 
‘flashing’ as would be the case if the ‘on’ attribute was 
sent first. 


Normally, highlight type zero, the default, is set to 
method zero and no highlight sequences are specified 
for it. However if all the attribute methods are code 3 
or 4 it may possible to dispense with all the ‘off 
sequences, and use the ‘on’ sequence for type 0 to 
reset any attributes to the ‘normal’ state. In this case 
the method code for highlight code 0 should also be 
set to 4. 


Cursor and Screen Size Section 


The PANEL Plus system will send up to four different 
sequences to the screen for addressing purposes. Firstly, 
different sequences are provided for ‘visible’ and ‘invisible’ 
cursor definition. Both sequences must be specified, even if 
they are identical. Some terminals allow direct screen buffer 
addressing, so that characters can be written to the screen 
while the cursor is positioned elsewhere. If this function is 
available, the PANEL Plus system will use it for all writing to 
the screen, only moving the cursor to fields where entry is 
required. This provides a much more restful life for data entry 
operators, since the cursor is not constantly flashing about the 
screen. On systems without this feature, it may be simulated if 
the cursor display is programmable, by including a sequence to 
turn off the cursor display in the ‘screen buffer addressing’ 
sequence, and one to turn it on in the ‘cursor addressing’ 
sequence. Be careful not to cause delays by overloading this 
sequence with functionality, though. 


Secondly, the PANEL Plus system allows for different control 
sequences to be used for two different halves of the screen. 
There are terminals which have different row bias values for 
the top and bottom halves of the screen, and in some 
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132-character line terminals the cursor positioning lead-in 
sequence, and the bias, are different beyond a particular 
column position. The PANEL Plus system only allows one 
division of this type, which may be ‘vertical’ or ‘horizontal’. 


The convention used for row and column numbers in the 
PANEL Plus system is that the top left corner of the screen is 
(0,0), and all bias values are calculated on this basis. 


Two different methods of specifying position values are in 
common use, either a binary value in a single character, or 
ASCII coded decimal values taking one, two, or three character 
positions. The PANEL Plus system can output sequences using 
either method, and allows an ASCII sequence to be defined 
either as variable length or as a fixed length of two or three 
characters. 


The control sequences for this section must fit into a data area 
of 64 bytes. As before, each character other than Oxff is treated 
as a normal data character, but the Oxff character is in this case 
treated as the first of a two- or three-character sequence. If 
the Oxff is followed by a binary zero value, it signifies that a 
delay is to be introduced as described above. The other valid 
characters following the Oxff character are codes of binary one 
through binary eight. In each case the next following character 
is treated as a bias value. The meanings of the codes are as 
follows: 


Binary column coordinate 
Decimal column coordinate (V) 
Binary row coordinate 

Decimal row coordinate (V) 
Decimal column coordinate (2) 
Decimal row coordinate (2) 
Decimal column coordinate (3) 
Decimal row coordinate (3) 


CONN NB WN 


Page 21-16 THE PANEL PLUS ‘TAILOR’ SYSTEM 


Cursor and Screen Size Section 


As an example, the positioning sequence for an ADM3a 
terminal (escape = y x) would appear as: 


21 61:2535 332.255 132 


A total of 64 bytes is available for the positioning sequences, 
and the detailed specification of the parameters in this section 
is as follows: 


e MAXC, MAXR (Maximum Column and Row 
Numbers) 
These values specify the size of the screen and normal 
values for the standard 80 by 24 screen are 79 and 23. 
(Remember that the top left corner is 0,0). The values 


are held in single bytes and the maximum is therefore 
299 


e XDIV, YDIV (Vertical and Horizontal Divisions) 


These two values specify the screen coordinate after 
which the second set of cursor addressing sequences 
will be used. Only one of these values may be used, 
and the other should contain a value larger than the 
maximum column and row numbers (typically 254). In 
the majority of cases the screen is addressed without 
any discontinuity, and both values are then set to 254. 


When the cursor addressing or screen buffer 
addressing function is invoked, it will use the 
appropriate second sequence if either the ‘x’ 
coordinate is greater than XDIV or the ‘y’ coordinate 
is greater than YDIV. 


e SBA1, SBA2 (Screen Buffer Addressing) 


These sequences specify the codes for direct screen 
buffer addressing for the first and second halves of the 
screen. If the screen buffer addressing function is not 
available, the sequences should be the same as those 
for cursor addressing. The second sequence is not 
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defined if the entire screen is addressed in the same 
way. 


e CUR1, CUR2 (Cursor Addressing) 


These sequences specify the codes for cursor 
addressing. The second sequence is not defined if the 
entire screen is addressed in the same way. 


Keyboard Code Section 


All function keys used by the PANEL Plus system are 
user-definable. The system can recognize function keys which 
generate single codes or code sequences of any length. 
Multiple code sequences are identified using the following 
recognition strategy: 


Up to four different single characters may be defined as a 
‘prefix’ code or ‘lead-in’ for multiple sequences. When a prefix 
character is read from the keyboard the system first waits for a 
specified period to see if any codes immediately follow. This 
period is determined by the input delay parameter. If no 
character is detected, the first input character is tested against 
the function key list to see if it is defined as a single-code 
function. This will often be the case with the escape key. 


If a character follows within the time limit, the PANEL Plus 
input routine enters a ‘multiple code’ mode. First, the system 
can be set to ignore a specific number of characters following 
each prefix. This allows for keyboards where the keys generate 
a lead-in sequence of more than one character. Then the 
significant character of the sequence is read and the character 
pair of prefix and significant character is tested against the 
function key list. The special case of two escape characters is 
detected even if a code specified to be always ignored after 
escape. 


If a match is found in the list, PANEL Plus can then be 

instructed to ignore a further number of characters, which may 
be different for each function. This allows for keyboards which 
append trailing characters after certain function key sequences. 
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If the sequence is not identified as a valid function any such 
trailing characters will either be treated as data or as the start 
of a new input sequence. 


The only restriction on multiple code sequences is therefore 
that for each prefix, there must be a fixed position in its 
possible following characters where a unique identifying code 
appears. 


The Keyboard Code section of the record defines the prefixes, 
the numbers of ignored characters, and the table of two-byte 
entries which holds the significant characters for each function. 
The second byte of single code function entries is null. 
e PREF (Prefix Codes) 
Up to four different codes may be defined as prefixes. 
Any character which appears in this table will be 
treated as a prefix character as described above. 
Empty entries cause ‘null’ to be treated as a prefix: this 
feature implements the standard prefix for the IBM 
Personal Computer. 
e IGNP (Prefix Ignore Numbers) 
Four numeric values, each corresponding to a prefix, 
indicate the number of immediately following 
characters which are to be ignored after detecting a 
prefix. 
e Input Function Table 
This table of twenty two-byte entries contains the 
character pairs which will be recognized as the 
following functions: 


1 CR Carriage Return 

2 ESC Escape 

3 BS Destructive Backspace 
= LEFT Cursor Left 

5 RT Cursor Right 

6 UP Cursor Up 
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7 DOWN Cursor Down 

8 ERAS Erase Line 

9 INS Insert Character 

10 Biss # Delete Character 

11 LINS Insert Line 

12 LDEL Delete Line 

13 TAB Tab 

14 ORY Query 

15 HOME Cursor Home 

16 PF 1 Program Function 1 
Le PF2 Program Function 2 
18 se ae Program Function 3 
19 PF4 Program Function 4 
20 PF5 Program Function 5 


The detailed reaction of the PANEL Plus system or of 
a user-written program to each function will depend on 
how each program has been written. 


e IGN (Function Ignore numbers) 


Twenty numeric values, each corresponding to a 
function, indicate the number of immediately following 
characters which are to be ignored after identifying a 
function. 


e Extended Program Function Key Table 


For special applications, the number of ‘program 
function keys’ available can be increased above five. 
This can only be done for systems which generate a 
maximum of two codes for each key, that is, the IGN 
table is empty because no trailing keystrokes have to 
be ignored. The input function table can conveniently 
be extended into the IGN table: when this has been 
done, a terminator character of Oxff is placed at the 
end of the extended table. The normal maximum 
extension of the input table is therefore nine 
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character-pairs, making a total of 14 definable 
‘program function keys’. The presence of the special 
terminator indicates that extra function keys have been 
defined, and its position defines the number of such 
keys. 


e Comments Section 


A space of 512 bytes is provided for comments on the 
customising. This space is divided as follows: 


80 bytes: 3 Screen output functions 
32 bytes: Delay specification 

10 bytes each: 16 Attribute types 

40 bytes: Cursor positioning 

10 bytes each: 20 Keyboard functions 


IBM Personal Computer Tailoring Features 


When tailoring for the IBM Personal Computer or compatible 
systems under PC-DOS or MS-DOS, the Terminal ID field 
must start with the five characters ‘IBMPC’ (in capital letters). 
This signals to PANEL Plus routines that IBM-compatible 
ROM BIOS calls can be used. If the ID field starts with 
‘IBMPC ’ it is important that you do not attempt to run any 
PANEL Plus system programs on a non-compatible system: 
PANEL Plus functions will attempt to issue software interrupts 
to access IBM PC BIOS functions which may have unexpected 
consequences in another system. 


The special functions described in the remainder of this 
subsection for the IBM Personal Computer are brought into 
operation by the ‘IBMPC’ at the start of the terminal ID field. 
When using the IBM Personal Computer with a terminal driver 
which accepts escape sequences, these initial five letters of the 
terminal ID code must not be used. This applies to the 
PC-DOS ANSI terminal driver as well as to CP/M-86. 
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e Screen Functions Section 


For the IBM Personal Computer, the only sequences 
which should be coded are those for the INIT, TERM, 
and BELL sequences. Any other function sequences 
will be ignored. 


The BELL sequence can be left empty if you wish to 
silence the beeper, or have the single value 7 to sound 
the standard ‘beep’. If two values are defined, the first 
is a frequency divisor and the second is a duration. 
Increasing the first value lowers the frequency. 


The INIT and TERM sequences are set up in a special 
way: the first byte signifies the colour screen mode as 
follows: 


40 x 25 monochrome 
40 x 25 colour 

80 x 25 monochrome 
80 x 25 colour 
monochrome monitor 
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The second byte has the ‘base’ screen attribute, to 
which the screen will be set by PANEL Plus on a clear 
screen operation. A full description of the codes for 
this attribute will be found in the IBM Personal 
Computer Technical Reference Manual. In summary, 
the codes are as follows: 


Bit 7 set selects a blinking foreground character 

Bits 6, 5 and 4 set up the background colour 

Bit 3 selects high intensity monochrome or alternate 
colour 

Bits 2, 1 and 0 set up the foreground colour 
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The colour codes are defined as follows: 


Colour Monochrome 
v Black Non-Display 
1 Blue Underline 
es Green 
3 Cyan 
4 Red 
S Magenta 
6 Yellow 
7 White White 


The third byte is an attribute value which selects the 
border colour for the display. Bits 2, 1 and 0 specify 
the border colour. 


If fewer than three bytes are specified, the PANEL 
Plus routines will omit the relevant functions. The 
initialisation sequence clears the IBM PC screen. 


The termination sequence is coded in the same way as 
the initialisation sequence, and performs the same 
functions on exit from the program. Note that if you 
specify a termination sequence the screen will be 
cleared on program exit. 


e Visual Attributes Section 


The method code for each attribute which you wish to 
use should be set up as 4, except for the attribute to be 
used for messages which should be set up as 132 (see 
above). The ‘attribute on’ sequence consists of a single 
byte, defined as described above for the second byte of 
the terminal initialisation sequence. The ‘attribute off 
sequence is not used. 
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The ‘highlight modifier’ is implemented for the IBM 
Personal Computer as follows: the actual value of the 
modifier is combined by ‘logical or’ with the attribute 
defined in the ‘on’ sequence for the highlight type. 
This allows selection of more combinations of 
background and foreground colour than are available 
with the 16 PANEL Plus highlight types. Remember 
that the ‘modifier’ only works when a method has been 
defined for the highlight type. 


e Cursor and Screen Size Section 
The MAXC, MAXR, XDIV and YDIV parameters are 
set up as for a standard system. SBA1 and CUR1 each 
contain two bytes giving the start and stop line 
numbers for the cursor within a display cell, in the 
range 0..13 for monochrome and 0..7 for colour. For 
SBA1, these values should be coded so that the cursor 
does not appear. The values for CUR1 can be used to 
select a line or block cursor as required. 


Note that if you use a higher value than 7 to set a 
monochrome cursor and then run the programs on a 
colour screen the cursor may completely disappear. 
The same effect occurs on a system such as the 
COMPAQ computer which combines mono and 
graphics on one display board. 


You should ensure that the value of MAXC is set 
correctly to 39 or 79 to match your choice of colour 
mode. 


If the MAXR value is 42, the system attempts to switch 
to 43-line EGA operation. 
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TI Professional Computer Tailoring Features 


The Texas Instruments Professional Computer has no 
‘background’ colour facility, but a full set of attributes such as 
inverse and underline is available for each colour. 


The provided screen attribute parameters for types 4, 5, and 6 
are set up for normal, reverse video, and underline 
respectively, and require the colour to be defined by means of 
the highlight modifier according to the table below: 


Colour 
Black 
Red 
Green 
Yellow 
Blue 
Magenta 
Cyan 
White 
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Wang Professional Computer Tailoring Features 


The monochrome mode for this system is basically standard 
ANSI. The ‘screen buffer address’ mode is implemented in the 
supplied tailoring file by setting the ‘hold cursor’ mode, leaving 
the cursor static but switched on, during a write operation. 

This is generally preferable, when available, to switching off the 
cursor entirely, as it gives the operator a clearer view of entry 
positions on the screen. 


In the colour mode on the Wang Professional Computer, the 
foreground and background colours are also selected separately 
from the display attributes such as inverse and underline. The 
default correspondence between numbers and colours can 
however be changed using an initialisation string as described 
in the Wang ‘Program Development Guide’. This guide also 
gives details of how to select colour or monochrome on systems 
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with more than one screen. It is suggested that the 
initialisation string for this system be set up with some care to 
correspond to your application requirements. 


The Wang Keyboard is unusual in not having an ‘escape’ key. 
In the supplied PANEL Plus tailoring file the ‘backtab’ key is 
used for the escape function because it is positioned on the 
keyboard where most people would look for an escape. The 
EXEC key is used for PANEL Plus function 1 and the COPY 
key for PANEL Plus function 5. 


Victor 9000 / Sirius 1 Tailoring Features 


The supplied files contain standard escape sequences for a 25 
by 80 screen, and the initialisation sequence is used to set the 
correct operating modes. The clear screen sequence clears the 
bottom line of the screen separately. 


The fact that all the keyboard codes are ‘soft’ means that there 
is no universal ‘standard’ keyboard layout. Use the tailor 
‘interactive keyboard specification’ to set the PANEL Plus 
function key definitions to the codes actually generated by your 
machine. 


ACT Apricot Tailoring Features 


The description of the supplied files for Victor 9000 and Sirius 
1 also applies to the ACT Apricot. The INIT sequence can be 
used to label function keys on the microscreen, but no standard 
labels are provided. If you use the microscreen, the TERM 
sequence should reset it to the standard date and time display. 


The keyboard program 


The keyboard program is designed to allow an operator to 
determine the keys used for each PANEL Plus function as 
defined in PANEL.VDU. It reads the PANEL.VDU 
information from the standard place and displays the name 
from the terminal ID field together with the labels (comment 
fields) defined for each of the twenty keys defined 3 in the key 
assignment table. 
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If more than the first five function keys have been assigned, 
this fact is noted, but there are no comment fields for 
additional keys. The program does not use the output code 
fields in PANEL.VDU and can be safely run from a terminal 
which does not match the current contents of the file. 


The vdugenc program 


vdugenc is used to generate a C source file which can be 
compiled and linked with an application to ‘hard-wire’ it to a 
specific screen and keyboard. The output consists of a pavdu 
array initialised with the contents of PANEL.VDU (from the 
current directory). 


The command syntax is as follows: 


vdugenc filename 


The output filename argument must be supplied and has any 
filename suffix removed and replaced by ‘.c’. An existing file 
of the same name will be overwritten without warning if it 
exists. 


The contents of the generated file must be included in the 
PSCO01.C module instead of the declaration of an uninitialised 
pavdu array. 


THE PANEL PLUS ‘TAILOR’ SYSTEM Page 21-27 


The vdugenc program 


or  ———— 
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USING PANEL PLUS ON AN IBM PERSONAL 
COMPUTER 


Introduction 


PANEL Plus provides four ways of running programs on an 
IBM Personal Computer or compatible system under PC-DOS 
or MS-DOS. In order of increasing display speed, these are as 
follows: 


e Using a graphics mode with a supported graphics 
library product 


e Using the ANSI terminal driver. 
e Using the ROM BIOS functions. 
e Direct I/O to the screen regen. buffer. 


This section provides additional information about using and 
customising each of these options. Please note that in the rest 
of the section we shall use IBM PC to refer to an IBM Personal 
Computer or a fully compatible system. Throughout this 
section we assume operation under PC-DOS or MS-DOS. 


Selecting the display method 


The factors affecting the selection of which method to use for 
screen display are performance, portability, and hardware and 
software compatibility. To make your selection, we 
recommend reviewing the following list: 


e To use the direct method, you must link your 
application with an optional ‘T library as described 
below. This library is supplied to provide a convenient 
way of incorporating PSC02 and PKB02 modules. 

Such an application will then only run on hardware 
which has a memory mapped display in the same 
position as an IBM PC. 
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e The direct method is substantially faster than any other. 


e The routines for the direct method also support a 
Microsoft or compatible mouse. 


e When you link your application without the ‘I’ library 
you retain the maximum flexibility. You can use the 
PANEL Plus tailoring system to select either the ANSI 
or the ROM BIOS method without changing the 
application .exe file. The same application will also 
run on non-IBM-compatible systems and terminals. 


e The ANSI method is often slower, but it may enable 
you to retain compatibility with certain non-standard 
operating environments. Note that the presence of 
ANSLSYS in your CONFIG.SYS file does not require 
you to use the ANSI method if others are available. 


e The direct method produces programs which are 
‘well-behaved’ under Microsoft Windows or IBM 
Topview, and which will run efficiently in a window 
which can be moved and sized. 


e You may be able to modify the low-level source 
routines provided for the direct method so that your 
application runs in memory-mapped mode on 
non-IBM-compatible hardware. 


e The graphics mode will allow your applications to 
display graphics integrated with PANEL Plus data 
entry and validation. 


Customising the ANSI parameters 
Select the ‘IBM PC ANS’ parameters using tailor. 


The IBM PC ANSI screen attributes are controlled by escape 
sequences in the same way as a terminal. To change the 
colours, you can select other SGR (set graphics rendition) 
sequences either for the clear screen or the attribute on and off 
sequences using tailor. The PANEL Plus highlight method 
code should be set to 4, except for the highlight type which is 

to be used for messages, which is set to 132. 
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You can use the highlight modifier to alter colours by inserting 
a special ‘M’ code in the escape sequence before the second 

byte of the colour number. The modifier will be or’ed with the 
second byte of the number, which should normally be set as ‘0’. 


Customising the ROM BIOS parameters 


Select the ‘IBMPC C80’ or ‘IBMPC MONO?’ parameters using 
tailor. The five letters ‘IBMPC’ at the start of the name 
indicate that the ROM BIOS calls are to be used. 


The ROM BIOS screen attributes are controlled by the INIT 
sequence and the attribute ON sequences. The three bytes of 
the INIT sequence indicate the screen mode, the base physical 
attribute for screen clear operations, and the border colour 
attribute. We use the same attribute values as defined in the 
IBM Technical Reference Manual, and a copy of the colour 
values also appears in chapter 21 of this manual. 


You can select a physical attribute for each of the 16 PANEL 
Plus highlight types and enter it as the appropriate ‘attribute 
on’ sequence using tailor. In each case the ‘off’ sequence is 
not used, and the method code should be 4 except for the 
highlight type to be used for messages, which should be 132. 


We recommend entering the physical attribute in hexadecimal 
(by following it with an ‘H’ in tailor), so that it is easy to 
distinguish the background colour in the first nibble from the 
foreground colour in the second. 


The highlight modifier for the ROM BIOS method is actually 
or’ed with the physical attribute. You can either specify a zero 
attribute and control the colour entirely with the modifier, or 
you can select foreground or background with the attribute and 
the other half with the modifier. 


When the ROM BIOS method is in use the papage and pachcel 
functions select display pages and border and clear screen 
attributes as described in the reference section. 
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Note that some other tailor parameters starting ‘IBMPC’ are 
used for systems which are nearly compatible ata ROM BIOS 
level. The ‘CMPQ’ parameters are used for early Compaq 
systems, but later ones seem to work fine with the normal 
‘IBMPC’ parameters. 


Customising the Direct I/O Parameters 


The ‘direct’ method makes no use of the PANEL. VDU file. 
All the customising of screen attributes is done through tables 
in the program. Some of these tables can be modified by use 
of DOS environment specifiers as well as by program. The 
tables appear in the low-level I/O modules PSC02.C and 
PKB02.C, and can either be modified dynamically by your 
program or by recompiling this module. If you refer to pai... 
variables in your main program, then it must obviously be 
linked with the ‘T’ library. 


The screen display attributes are selected from either a 
‘monochrome’ or a ‘colour’ set (paimat or paicat) by testing 
the hardware screen mode during painit processing. The 
appropriate parameters are placed in the paiatt table. The 
table has 16 bytes corresponding to the sixteen PANEL Plus 
highlight types, and each byte contains an IBM PC physical 
attribute. The first byte is used for the default, or base, screen 
attribute, and the second is selected for messages. There is no 
‘method code’. 


Environment specifiers are used as follows: 


e The PNLMONO environment variable can be set to a 
non-null value (at least one blank) to force the 
selection of the ‘monochrome’ attribute set on systems 
with a mono graphics CGA-compatible display. 


e The PAIATT environment variable can be set toa 
hexadecimal string which will replace the paiatt array. 
As an example, the command SET PAIATT = 120156 
will select ‘12’ as the first entry (green on blue), ‘OP as 
the second (bright white on black) and ‘56’ as the third 
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(yellow on magenta). Remaining entries in the paiatt 
array, if defined, will be unchanged. 


e The PAIBOR environment variable can also be set 
with a hexadecimal (two-character) value. For 
example SET PAIBOR = 04 will select a red border. 


Further information on customising the direct parameters 
appears in the low-level source modules. The keyboard entries 
are table-driven in this version. 


Alternate Utility Programs 


The PANEL Plus distribution disks for PC-DOS and MS-DOS 
versions contain alternate versions of the panelp, pantest and 
testc programs named panelpi, pantesti, and testci. These 
programs are for use on IBMPC hardware only, and run much 
faster than the normal versions of the programs. Do not use 
these special programs on hardware which is not IBM 
compatible. The ‘I’ versions make no use of the PANEL.VDU 
file, 


The panelp program always operates in text mode, except in 
versions like the native Amiga version where the only low-level 
interface is a graphics interface. You can relink the pantest 
program to produce a version which runs in graphics mode, 
which may help you to test your screen layouts in exactly the 
same mode as they will appear in your program. 


Linking programs for direct memory-mapped operation 


When applicable, additional libraries are provided with an ‘I’ 
suffix after the interface number. When you wish to link your 
program to use the direct screen method, name the ‘P library 
to your linker before, and in addition to the normal library. The 
memory-mapped I/O routines will then be used instead of the 
low-level routines in the normal library. The resulting 
programs will only run on IBM PC hardware. The ‘I library 
contains a second copy of the PUTIL module, which ensures 
that the low-level modules get loaded from this library in place 
of those in the standard library. 
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Linking programs for graphics mode operation 


The modules for graphics mode operation are not provided in a 
library. When you have selected and compiled the low-level 
module(s) to support your graphics library, you should include 
the object files in your link command file, or build your own 
library. If you build a special library analogous to the ‘T’ library 
you should include the PUTIL object file ahead of the 
low-level modules to ensure correct operation. 
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USING PANEL PLUS ON THE COMMODORE 
AMIGA 


This section provides additional documentation for PANEL 
Plus for the Commodore Amiga. PANEL Plus is available in 
both native Amiga versions and also for cross-development 
under MS-DOS or PC-DOS. Unless otherwise noted, the 
description below applies to all versions. 


The versions of PANEL Plus for the Amiga are designed to 
allow ‘traditional’ text-based data-entry applications to be 
written for the Amiga without having to get involved in the 
intricacies of the Intuition/AmigaDOS interface. Programs 
written with PANEL Plus for other environments should be 
able to be ported to the Amiga simply by recompilation using 
the native or cross-compiler versions of C. Although 
applications can be developed easily and quickly using PANEL 
Plus, they are able to use the advanced features of the Amiga 
and are fully integrated into the multitasking environment. 


Screen layouts created using PANEL Plus are generally 
portable between all supported environments. The only 
exception will be if you have included extended character set 
values in your screen designs, which may display differently 
when you move the application to the Amiga. Code generated 
by pangenc also needs to be regenerated for use on a machine 
with a different sequence of bytes in a word. 


Function calls to the PANEL Plus library are unlikely to 
require any change for the Amiga. Because the Amiga does 
not require the PANEL Plus tailoring system, it will correspond 
most closely to the memory-mapped option in the IBM 
Personal Computer versions of PANEL Plus. 
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Installation and Tailoring 


PANEL Plus programs, and applications created using 
unmodified PANEL Plus library routines, look for certain 
parameter files on a device named Panel:. Since the native 
Amiga version of PANEL Plus uses this as a volume name, the 
programs will work without requiring any assign statement. If 
you use Our programs, or those you have developed, on a disk 
with a different name, you must assign Panel: as a logical name 
to the appropriate physical volume. Alternatively, you may 
prefer to modify the low-level module PSCO5.C to use 
predefined parameters and avoid reading the parameter files. 


The tailor and keyboard programs are not used with the 
Amiga, and the PANEL.VDU file is also not required. 
Customising the PANEL screen and keyboard is done either by 
modifying the supplied low-level source module PSCOS.C or by 
using the configuration files pnlcolors, paiatt, or pnlmode. The 
Panel:pnicolors file contains the Amiga colour register values 
(R,G,B) for up to sixteen registers, which will be loaded as 
each program is initialised. This file will normally contain eight 
colour register entries to correspond to the default screen 
depth of 3, and the file can then be set up interactively using 
the pemu program. 


The Panel:paiatt file contains up to sixteen pairs of numeric 
values giving the foreground and background colour register 
number to correspond to the sixteen PANEL Plus highlight 


types. 


The Panel:pnlmode file contains sing]e-letter codes to select 
various screen modes. 


All three files are sought in the device Panel:, which must 
either be a physical volume name, or must be set with an assign 
statement, preferably in your file s:startup-sequence. If you 
forget to make this assignment, the program may appear to 
hang after opening the screen. To escape from this situation, 
press ‘Amiga-N’ to redisplay the workbench screen and then 
‘cancel’ the error requesters. On returning to the PANEL Plus 
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screen with ‘Amiga-M’ you will find that the program is 
working correctly, probably with unusual colours. 


The keyboard assignments are predefined for the supplied 
PANEL Plus utility programs (see the table below). In 
application programs you can modify the defaults by ne 
the tables in the supplied source module PKBOS.C. 


The Amiga Implementation 


PANEL Plus screen operations are implemented on the Amiga 
by opening a custom screen and a full-screen window with no 
sizing or close gadgets. Various screen modes can be selected 
using pnlmode as described below. 


The PANEL Plus screen and window can be accessed through 
the global pointers pascrn and pawind, and the TextFont 
Structure is also available through the pafont pointer. 


By default, no title bar is shown on the screen. This allows the 
full area of the window to be used for display. The absence of 
the title bar prevents you from pulling down the screen, so we 
have made a way for the user to turn on the title bar by means 
of a pull-down menu. Whenever a program is looking for 
keyboard input it will also look for the ‘menu’ (right) mouse 
button being used to drag either to ‘show’ or to ‘hide’ the title 
bar. Once the title bar is visible you can use the front/back 
gadgets in the normal way or use the title bar to drag down the 
whole screen. If you try to use the pull-down menu when your 
program is not checking for keyboard input, both menu check 
marks will disappear. You can of course switch to and from 
the Workbench screen using the Amiga-N and Amiga-M keys, 
even when the title bar is not shown. If a program under 
development appears to hang, always try using the Amiga-N 
key to see if there are any requesters on the workbench screen. 


Input from the keyboard is processed though a raw console 
device, which returns escape sequences for the function keys 
(not raw keycodes). These escape sequences are analysed in 
exactly the same way as for other versions of PANEL Plus. 
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The keyboard input process also checks for mouse and menu 
selections. 


To check for other input events, assign a value to paidcm, 
which is a pointer to a function returning an integer. Your 
function will be passed the IDCMP message. 


Output to the PANEL Plus window uses the Amiga graphics 
text functions for maximum speed. Saving and restoring screen 
contents for field overlays is done with BltBitMap, and appears 
instantaneous. All output appears in one backdrop window, 
and the Amiga layer library is not used. The DOS cursor is not 
used, and PANEL Plus implements a cursor as a graphics 
rectangle, also with BItBitMap. Box/Borders are implemented 
as a Series of line-draws. 


The provided source code in PSCOS.C allows all aspects of the 
PANEL Plus Intuition interface and keyboard input 
environment to be modified as required. 


Icons are provided in .info files for several PANEL Plus 
programs. Each program can also be called from the CLI, 
using program arguments if applicable. 


The PCMU ColorMap Utility 


pemu is the PANEL Plus ColorMap Utility. It is used to 
maintain the file Panel:pnicolors which contains eight sets of 
three numeric values for the Red, Green, and Blue settings of 
the corresponding Amiga colour register. 


The pnilcolors file is listable. Each line in the file must be 
exactly 9 bytes long, plus a newline, and must contain three 
values between 0 and 15 inclusive. When the ‘save’ option is 
selected, a backup copy of the file is made as 
PANEL:pnlcolors.bak. 


To run pemu, enter the name on a CLI command line or select 
the icon. Adjust the R, G, or B values by clicking the select 
button on the appropriate numeric value in the three columns 
on the right of the screen, and then clicking one or more times 
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on the ‘+ +’ or ‘--’ as required. The default colours for 
PANEL Plus and for the pemu screen are a foreground of 1 
and background of zero. If you adjust these two colours to the 
same register values you will have to select your mouse click 
targets by feel rather than by sight. 


When you have set all the colours you wish to use, make a note 
of up to sixteen pairs of foreground and background colour 
numbers (shown in the test colour patches) each PANEL Plus 
highlighting type which you plan to use. We strongly 
recommend that the highlighting type zero (default) should use 
foreground colour 1 and background colour 0. These pairs of 
values are then set using paiatt as described in the next section. 


Highlighting Attributes 


The file Panel:paiatt contains pairs of foreground-background 
colour numbers for each of the sixteen PANEL Plus 
highlighting types. The (up to 32) numeric digits are written in 
the file with no embedded spaces. If you specify fewer than 
sixteen pairs, or if the file is absent, the defaults from paiatt in 
PSC0S.C are used. 


The default attribute values are as follows: 
LO. 25 “is 42 6S 20 £0 30-73. 7 4 
OO Ee a OBO 2 OO J SS sy 


The defaults are selected to correspond roughly to the PANEL 
IBM Personal Computer colour defaults when the supplied 
pnicolors file is in use. 


Note that text written with the same foreground and 
background colour numbers will be invisible unless a highlight 
modifier is used. 


In this implementation, the highlight modifier byte high nibble 
is or’ed with the foreground colour and the low nibble or’ed 
with the backgound colour. As an example, a highlight 
modifier of hexadecimal 54 used with highlight type 15 will give 
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foreground colour 5 and background colour 4. The actual 
colours will depend on the pnilcolors settings. (Highlight 
modifers are specified as decimal values in the panelp program 


‘Define Attributes’ submenu). 


We recommend that the paizatt file should start "10...." so that 
the default background is colour zero and the foreground is 


colour 1. 


The default keyboard functions are assigned as follows: 


Carriage Return Return 
Escape Escape 
Destructive Backspace Back Space 
Cursor Left Left Arrow 
Cursor Right Right Arrow 
Cursor Up Up Arrow 
Cursor Down Down Arrow 
Erase Line F9 

Insert Character F6 

Delete Character DEL 

Insert Line F7 

Delete Line F8 

Tabulate TAB 

Query HELP 
Home F10 
Program Function 1-5 F1- FS 


These functions can only be changed by modifying the arrays in 
PKBO0S.C. 


Screen Mode 


The file Panel:pnlmode, if present, contains codes to override 
the default mode. The mode can also be overridden by placing 
a value in pamode before calling paosint. Defines for the 
pamode settings are supplied in PNLI.H. 


Page 23-6 USING PANEL PLUS ON THE COMMODORE AMIGA 


Global Variables 


Entries in the pnlmode file consist of upper-case letters or 
numbers as follows: 


S (PANELSIXTY) Set font size to sixty 
characters per line. 

L (PANELLORES) Set low resolution mode. 

I (PANELINTERLACEB) Set Interlace mode. 

Q (PANELQUIET) Do not use narrator device. 

1-5 Set screen depth to the given value. 


We recommend experimentation with some of the modes 
before deciding to use them in an application. If you use the 
60-column or low resolution modes you should ensure that you 
do not have messages or screen fields which overlap the screen 
as this can sometimes crash the system. This generally prevents 
the panelp and pantest programs being used other than in 
80-column high-resolution mode. 


Global Variables 


The following global variables are specific to the Amiga version 

of PANEL Plus. If you use them in your program, it should 

normally be done inside an ‘#ifdef AMIGA’ block to ensure 

portability. 

pamode Set before calling paosinit, with the flags 
defined in PNLI.H or’ed with each other and 
with the depth value. 

patbsh Set before calling paosinit, with a value of 
TRUE to force initial showing of Screen Title 
Bar. During execution, has current status of 
title bar (TRUE if shown). 


padept Screen depth (default 3). Set by paosinit. 
pacols Number of columns (default 80), set by paosinit. 
PAROWS Number of rows (default 25), set by paosinit. 
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PANROK Narrator OK to use (default TRUE), set by 
paosinit. 

PACWID Character width in pixels (default 8), set by 
paosinit. 

PACHEI Character height in pixels (default 8), set by 
paosinit. 

PAADAT AmigaDOS date (array of 3 ints), set by 
paosinit. 

PASCRN Pointer to PANEL Screen structure. 

PAWIND Pointer to PANEL Window structure. 

PAFONT Pointer to PANEL TextFont structure. 

PANARB PANEL Narrator IO Request Block. 


PAIDCM Pointer to user function to process IDCMP 
messages. 
Speech Functions 


The PANEL Plus Amiga version includes an additional 
Extended Attribute specifier, HS, for spoken help messages. 
The extended attribute string consists of a single string to be 
passed to the translator and narrator device. 


The PANEL speech function is implemented by the function 
panarr. The passed string can contain escape sequences 
introduced by a vertical bar character followed by the single 
character ‘M’, ‘F’, ‘N’, or ‘R’ (upper or lower case) for Male, 
Female, Natural, or Robotic respectively. The default is Male, 
Natural. 


Code generation for Cross-Development 


Please note the description of the pangenc option ‘-s’. This 
switch is pre-set for the cross-development version of PANEL 
Plus in the special version of PANGENC.MSG file which is 
supplied with the PANEL Plus Amiga files. Do not use the 
standard PANGENC.MSG file. 
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Using PANEL Plus with Unix and Xenix 


There is little to add to the main part of this manual to cover 
the operation of PANEL Plus in a Unix or Xenix environment. 
Your programs will normally be linked with the standard 
PANEL Plus low-level modules to configure terminals with 
PANEL.VDU, but for some PANEL Plus versions we also 
provide either low-level modules which operate through termio 
or hardware-specific low-level modules (e.g. for the IBM 
Personal Computer). 


Details of configuration options vary from one PANEL Plus 
version to another, and you should check the supplied 
documentation files for specifics. When a termio low-level 
module is available, special versions of the PANEL Plus utility 
programs may be provided (with a ‘t’ suffix, for example 
panelpt). 


The paneltc program supplied with certain PANEL Plus 
versions can be used to create a PANEL.VDU configuration 
file in the current directory automatically from a termcap entry. 
The syntax is as follows: 


paneltc [termcap_entry_ name] 


If a termcap entry name is not supplied, the current value is 
used. This utility cannot handle a termio database, and it only 
supplies standard entries for the keyboard table. We 
recommend that you use tailor to customise the keyboard after 
running panelte. 


The “‘compiler-specific’ source modules for Unix and Xenix are 
supplied in generic versions with non-Unix versions of PANEL 
Plus, and these will require some slight alteration for specific 
environments to which you may port your applications. In Unix 
and Xenix versions of PANEL Plus, the supplied 
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Using PANEL Plus with QNX 


‘compiler-specific’ module will have been tested in the 
particular environment for the version. It is important to make 
the right choice for the PATERMIO define, which is used to 
select the correct type of ioctl call. See the source file for more 
information. 


Using PANEL Plus with QNX 


The PANEL Plus version for QNX uses the supplied tcap 
feature for configuration to different screens and keyboards. 
The tailor program is not required. 


Using PANEL Plus with VMS 


PANEL Plus for VMS uses the standard PANEL.VDU file for 
configuring screens and keyboards. The following notes will 
help you to convert applications to VMS: 


e Programs which require command-line arguments 
should have their names defined with a command such 
as: PANTEST: = = <disk>:[< dir >]PANTEST 

e No attempt has been made to use ‘environment 


variables’. We recommend the use of logical names 
for PANEL.VDU and the various message files. 


e PNL files transferred to VMS must be converted as 
fixed-length record files with a record length of 32 
bytes. The TAILOR.DAT file has a record length of 
512 bytes. 


The low-level compiler-specific module for DEC C implements 
character-by-character input and buffered output. You may 
wish to modify the way this is done in order to comply with 
installation standards. 


Using PANEL Plus with other operating systems 


Please see the supplied documentation files for supported 
operating systems. If you move PANEL Plus library files to an 
environment not already supported by PANEL Plus, follow the 
guidelines in chapter 20 when modifying the low-level source 
modules. 
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PANEL PLUS 


This chapter outlines the considerations in converting 
applications developed using Roundhill’s PANEL library to 
work with PANEL Plus. 


Is is necessary to convert? 


As we have upgraded PANEL over the years we have always 
tried to maintain compatibility with earlier versions. But 
PANEL Plus is not just an upgrade to PANEL, and changing 
your application to use the PANEL Plus library is bound to 
involve at least some change to your program code. 


PANEL is still supported by Roundhill, and if you have an 
existing completed application which uses PANEL there is no 
real need to switch it to PANEL Plus unless you wish to 
enhance it to use some of the more powerful features of 
PANEL Plus. It is for these types of application that we have 
included some of the old function calls, so that you should be 
able to retain large sections of your application code when you 
wish to link it with PANEL Plus instead of PANEL. 


Screen layout compatibility 


All screen layout files developed with PANEL from version 
4.00 onwards can be edited with the PANEL Plus screen editor 
panelp (or its special versions panelpi or panelpt). Earlier 
versions than PANEL 4.00 supported CP/M-80 only and used a 
completely different file format. 


Versions of PANEL earlier than 6.00 did not support field 
overlays or level numbers, and the field in the .PNL file which 
is now used for level number was a spare field which in some 
circumstances could contain a non-zero value. To use such a 
file with PANEL Plus you must first read and write it with 
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panelp, using the -z command-line switch. This sets all level 
numbers to zero as the screen layout is read in. Do not use the 
-z switch with later screen layout files. 


The key field attribute indicator used in PANEL is no longer 
supported and the indicator is now used to specify a mandatory 
field. If you have screen layouts which used the key attribute 
you will have to change them to perhaps use a special line 
validation number instead. The PANEL library made no use 
of this indicator, which was only referred to in the pd sample 
data management program supplied with PANEL. pd is not 
included with PANEL Plus. 


Line validation numbers 211, 212, and 213 for displaying the 
system date are no longer supported, and if you have screen 
layouts containing fields with these codes they will have to be 
changed. The system date is now specified using the DF 
extended attribute as a special case of a default field value. 


The ‘X’ field attribute in a numeric or currency field no longer 
affects the acceptance of an empty field as a zero value. The 
acceptance of an empty field can now be controlled by the “M’ 
(mandatory field) attribute. “X’ still causes a zero field to be 
formatted as an empty field instead of with a zero value. 


Screen layout files written by the PANEL Plus screen editor 
panelp cannot be used reliably with PANEL because of the fact 
that they can now include fields on any of 127 levels and with 
data area size different from the displayed field size. 


Library differences 


Apart from the changes to the main field processing functions 
which are discussed below, we have made some smaller 
changes to functions and variable names which may not be 
apparent from a quick glance at the documentation. These 
changes are summarised in this section. 

» Lower case names are now used for all PANEL Plus 


functions and variables, leaving upper case for most 
macro and defined names. This change was made to 
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conform to accepted C programming practice, and to 
make it slightly easier to interface to non-C languages. 
If your compiler and linker are case-sensitive the 
PUPC.H file can be included in your application 
programs to translate from upper to lower case. 


e The paosinit and paosterm functions are now provided 
in all versions of PANEL Plus, instead of only when 
required. 


e The PANEL environment control block no longer 
exists. The version identifier numbers were not used 
anywhere and have been deleted, and the fields for 
‘terminal id’ and screen size have now become 
Separate variables patrid, pamcol, and pamrow. The 
array of displayable character indicators has now 
become local to the patdsp function. 7 


e The field read function pafir (and all functions that 
call it) now perform the line validation function, if 
defined, when a program function key is used, before 
the function finishes. This ensures that, for example, a 
numeric value in the current field is reformatted when 
a program function key is used to terminate a 
full-screen read operation. The escape key still causes 
an immediate exit (as used to happen with all program 
function keys). 


e The panels(pread) function now moves to the next 
field when PF key 1 is used, instead of terminating the 
read (as still happens with any other PF key). To 
revert to the old method of terminating on any PF key, 
add the switch LF1BRK to the list mode in the ‘pread’ 
case processing in the PANELS.C function. 


e The paload function no longer has a third argument 
which can be used to prevent an area being allocated 
for data in a dynamically loaded screen layout. We 
recently discovered that this feature was broken about 
two years ago anyway. 


CONVERTING PANEL APPLICATIONS TO PANEL PLUS Page 25-3 


Field and screen functions 


e The paansw function now returns a key function 
number, to be consistent with the PANEL Plus field 
read functions. The return value can be converted 
with pocode to match the return values from this 
function in PANEL. | 


e The library is no longer organised so that output from 
vdugence can be compiled and linked in. You have to 
modify the PSC01.C module to include it. 


e The null pointer define PANULL has been changed to 
separate values for null function pointers and null data 
pointers. If you have used PANULL in several places 
you may find it easier to add a define for it to your 
PNLLH file. 


Field and screen functions 


The main decision you have to make in converting a PANEL 
application to use PANEL Plus is whether to retain your 
PANELF and PANELS function calls or whether to convert 
them to the PANEL Plus calls. 


Our recommendation would be to convert: having tried it with 
the (admittedly relatively few) sample programs which we use 
to test PANEL and PANEL Plus we found it was a 
straightforward operation. Even if you retain the old calls you 
will have to re-test your application, and you may still decide to 
convert the calls at a later stage. 


Another advantage of converting is that the PANEL Plus 
function calls are more logically organised than in PANEL, and 
your converted program should therefore be easier to maintain. 


If you do convert whole-screen operations which currently call 
PANELS, you will no longer need to call PAUSEP to set up 
the static array PAFPT. You should remember that PAUSEP 
also sets the message line to the message line defined for the 
screen layout, so you may need to add a statement to Set pamin 
from the message line element in the panel control block. 


ci 
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If you have custom validation functions which were written for 
PANEL you can change them without too much difficulty for 
use with PANEL Plus. The concept of a ‘current field’ in a 
statically allocated PACRF structure no longer exists, and the 
validation function is passed a pointer to a field control block 
(which is in internal format). You will therefore need to alter 
your function argument specifications to match. Also the 
PNL4.H include file can be replaced with PVAL.H. 


For simple validation functions, the only changes required are 
to modify the function arguments and to change occurrences of 
the string ‘PACRF.’ to the string ‘fp->1’. The ‘I’ is necessary 
because the structure element names for the internal fcb begin 
with ‘I’ (and those beginning with ‘data’ have been abbreviated, 
too). Some of the static variables used in validation functions 
(for example ‘inch’ for the input character) are now carried in 
the internal field control block structure. 


If you have based your custom validation on one of the 
supplied PANEL functions you should compare the PANEL 
and PANEL Plus versions of the original to highlight the 
differences. We recommend that any PANEL Plus field 
functions called from within validation functions should be 
those which use the internal field control block format. There 
are now no restrictions on recursion, so you can call a PANEL 
Plus read function for another field while you are in the middle 
of a validation operation. The only thing you must remember 
is to set the flag in the return code which forces PANEL Plus 
to clean up the cursor position and highlighting. 


Menu functions 


A number of PANEL users modified the supplied PAMENU 
function to operate in different ways. We have effectively 
rewritten the PAMENU function in PANEL Plus to improve 
performance by using some of the new field primitive 
functions. Before rewriting your own menu function to match 
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this, you should look at the PANEL Plus pmenu function to see 
if this will do the job. pmenu has been designed as a ‘smart’ 
menu function which will adapt its operation according to the 
shape and content of the menu field you pass it. 


Stack usage 


Although there is much less use made of static data areas in 
PANEL Plus than in PANEL, we have to keep working data 
somewhere in PANEL Plus, and where we keep it is in 
automatic variables on the stack. All the test programs we 
have so far tried operate successfully with the default stack size 
set by the compiler and linker, but if your application was near 
the stack size limit, converting to PANEL Plus might just push 
it over the top. If you suspect that this may be a problem, use a 
compiler option to insert stack probes at the start of each 
function, or increase the stack size. 


Heap usage 


In most cases, a PANEL Plus program will use about the same 
amount of heap space as the equivalent program written with 
PANEL. If you plan to link a program with one of the graphics 
versions of the PANEL Plus low-level modules, be prepared 
for a big increase in the space needed for saving screen 
contents under pop-up fields. Make sure that you test your 
program on the highest resolution screen supported by the 
graphics library. 


Program size 


Our experience is that programs written with PANEL Plus 
result in slightly smaller executables that the equivalent 
program written with PANEL, despite the extra functionality. 
This is partly due to the increased granularity of the library, 
and partly to the shift from static to automatic variables. 
Applications which use a lot of ‘empty’ window fields can make 
significant savings in space by defining them in panelp with a 
‘one-byte by one-byte’ data area. 
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Attribute definition 4-3 


B 


Background keyboard operations 18-3 
Background screen 4-2, 8-1, 8-10 
BACKSLASH define 12-6 
Backspace 5-3 
BD extended attribute 6-8 
BIX 2-1 
Blank fill characters in field 13-20 
Border attribute 6-3 
Borders 
Border character specification 6-8, 21-13 
Border legend 6-9 
Border-only display 6-9, 13-12 
Default and alternate 6-8, 13-12 
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Definition using panelp 6-9 

Field borders 6-8 

Force spaces as border characters 13-12 
Bottom right position of screen 13-10 
Break on list error 13-2 
Browse function 14-9 
Buffered output 12-6 
Built-in validation 6-2 
Byte Information Exchange 2-1 
Byte sequence in word 10-4, 12-6 
BYTESWAP define 12-6 


& 


Carriage return 5-3 

Carriage return with no data keyed 13-15 
Cast, on constant 10-3 
Centering a field 8-14 
Character list validation 6-4, 6-7 
Character validation 4-3, 19-4 
CL extended attribute 6-4, 6-7 
Clean-up after keyboard process (pakcln) 12-10 
Clearing a field to fill 13-8 
Clearing the screen 13-6 

Code generation 4-3, 4-5 
Compiler selection 12-5 
Contiguous memory 4-5 
Converting from PANEL 1-4 
Copying a field 8-13 

CR required attribute 6-2, 14-7 
Currency fields 12-8 

curses 1-2 

CURSHAPE define 12-6 
Cursor addressing 21-15 

Cursor down 5-4 

Cursor left 5-3 

Cursor right 5-3 

Cursor shape 12-6, 18-10 
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Cursor up 5-3 
Custom validation 4-3 


D 


Data area size 8-10 

Date validation 6-6 

Date, system 12-6 

DATETIME define 12-6 
Decimal point 6-2 

Default field value 4-2, 6-12, 13-8 
DEFAULT mode switch 13-3 
‘define’ program 4-4, 8-7, 9-3 
Delay parameters 21-11 

Delete character 5-4 

Delete line 5-4 

Deleting a field 8-15 

Deletion of a field 8-12 

DF extended attribute 6-11, 13-8 
Displayable characters 6-4 
Displaying a field 13-10 
‘document’ program 4-5, 9-4 
Dollar attribute 6-3 

DOLLAR define 6-10, 12-8, 12-12 
Dynamic load 4-3, 13-21, 13-24 


E 


Echo attribute 6-2 

Emitted string validation 6-5 
Entry prompts 8-2 

‘enum’ program 4-4, 8-7, 9-3 
Enumerated set 10-3 
ENVIRON define 12-6 
Environment 12-6 
Environment variables 3-4 - 3-6 
Erase line 5-4 

Escape key 5-3 

Escape sequences 21-4 
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Extended attributes 4-3, 6-1 
Customisation 6-1, 6-12 
Definition 8-9 
Limit on number of substrings 17-13 
Substring delimiters 6-1 
Substrings 6-1 
Use with FORTRAN 6-1 


F 


FBORDA mode switch 13-12 
FBORDD mode switch 13-12 
FBORDO mode switch 13-12 
FHELP mode switch 13-16 
FHSCRO mode switch 13-16 
Field 1-2, 4-2 
Field attribute defines 12-5 
Field attributes 4-2, 8-8 
Field control block 1-2 

Abbreviated 10-3 

Format 16-1 

Full 10-3 

‘Internal format’ 7-8 

Old format 10-4 
Field control block pointer array 13-1 
Field data area 1-2, 8-10 
Field display 13-10 
Field fill to blank 13-20 
Field initialisation 4-2, 8-7 
Field list index (paflx) 12-10 
Field list operations 13-1 
Field lose 13-19 
Field mask 8-7 
Field name 4-3, 4-5, 8-6, 10-3 
Field name prefix 8-7, 8-16, 10-4 
Field prepare 13-7 
Field prepare function 6-12 
Field read 13-14 
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Field save areas 13-11 
Field scrolling 13-16 
Field sequence 4-2, 8-17 
Field sequence numbers 8-17 
Field tracking 12-7, 18-5, 18-13 
Field tracking switch (patrkn) 12-12 
Field unshow 13-18 
Field validation 19-8 
FIELDTRACK define 12-7 
File names, case of 12-7 
Fill character 8-8 
Finishing PANEL Plus operations 13-5 
FKNUMB define 12-6 
Floating point operations 12-8 
FLUSH define 12-6 
FNOVER mode switch 12-12, 13-12 
fopen function 12-8 
FOVER mode switch 13-12 
FPNC mode switch 13-8 
FRDHI mode switch 13-16 
Freeing space used by loaded screen 13-24 
FSPBD mode switch 13-12 
Full field control block 10-3, 13-22 
Function key numeric values 12-6 
Function names 

See Naming convention 
Function prototypes 12-8 
Functions 

paansw 8-4, 14-4, 25-4 

pabf 17-2 

pabm 17-2 

pabrw 14-9 

pachcl 18-2 

-pacinp 18-3 

pacout 18-5 

pacsta 18-6 

pacurs 18-7 
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padrba 20-5 
padrbb 20-5 
paeout 18-8 
pafd 13-10 
pafde 17-6 
paffb 13-20 
pafgs 17-5 
paficf 16-9 
pafich 16-10 
pafid 16-4 
pafide 16-4 
pafidf 16-5 
pafidh 16-7 
pafidl 16-8 
pafier 16-10 
pafifb 16-4 
pafifm 16-9 
pafifr 16-9 
pafigp 16-4 
pafigs 16-4 
pafihc 16-7 
pafiil 16-8 
pafilf 16-4 
pafilo 16-12 
pafimm 16-9 
pafip 16-4 
pafipd 16-12 
pafipl 16-12 
pafipn 16-12 
pafips 16-4 
pafir 16-4 
pafirn 16-4 
pafish 16-10 
pafiuc 16-7 
pafiuf 16-4 
paflf 13-19 
pafp 6-8, 6-10, 6-12, 13-7 
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pafps 17-5 

pafr 6-6, 13-14 

pafree 13-24 

pafuf 13-18 

pafunc 13-4 - 13-6, 18-9 
pagetf 13-15, 18-11 
pagfln 18-13 

painit 13-4, 18-2, 18-14 
paix 17-2 

pakini 18-14 

paktrm 18-9, 20-6 

pald 13-10 

palfb 13-20 

palift 20-5 

pallf 13-19 

paload 13-21, 13-26, 25-3 
palook 13-21, 13-25 - 13-26 
palp 13-7 

palr 13-14 

paluf 13-18 

pamenu 15-15 

pamlcl 13-25 

pamlop 13-21, 13-25 
pamsge 8-4, 14-2 

panelf 15-2 

panels 15-11, 25-3 
panexp 17-4 

panimp 17-4 

paosinit 13-4, 18-16, 25-3 
paosterm 13-5, 18-16, 25-3 
papage 18-17 

papd 13-10 

papfb 13-20 

paplf 13-19 

papp 13-7 

papr 13-14 

papuf 13-18 
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pardsp 20-5 
parout 18-8 
pasbad 18-7 
pascnl 15-14 
pascse 13-4, 18-18 
pasout 18-8 
pasvin 13-11, 17-10 
pasvlf 20-5 
patdsp 6-4, 25-3 
pausep 15-10 
paxagn 17-12 
paxase 17-12 
paxast 17-12 
pelear 13-6 
pfinish 13-5 
phlpof 19-3 
phipon 19-3 
pmenu 14-6 
pocode 17-9, 25-4 
prelxy 17-8 
pscana 4-4, 17-7 
pstart 12-13, 13-4, 17-10 
FVSCRO mode switch 13-16 


G 


Global variables 
(Amiga-specific) 23-7 
paflx (field list index) 12-10, 13-15, 15-11 
paflxs (saved field list index) 12-10, 13-15, 15-11 
pafpt (field pointer table) 15-1, 15-10 - 15-11, 15-14 
paftrk (field number to track) 18-5 
painme (insert mode enable) 19-3 
painmo (insert mode on) 19-3 
pakbfp (keyboard function pointer) 12-10, 18-3 
pakbtt (keyboard translation table) 20-3 
pakcln (clean-up switch) 12-10, 18-4 
pakeyt (keyboard table) 20-3 
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pamaxd (numeric array size) 12-11 
pamaxl (numeric array size) 12-11 
pamcol (max column number) 12-11, 18-14, 25-3 
pamen (message end point) 12-11, 14-2, 14-4 
pamfcb (message field control block) 14-2 
pamhd (message heading) 12-11, 14-2 
pamln (message line) 12-11, 14-2, 14-4, 15-10 
pammap (memory-mapped switch) 12-11 
pamous (mouse switch) 12-11 
pamoux/pamouy (mouse location) 12-11 
pamrow (max row number) 12-11, 15-14, 18-14, 25-3 
pamult (multiple PNL file control) 12-11, 13-21 
panfl (number of fields) 15-10 
panumd (numeric currency array) 12-12 
panuml (numeric integer array) 12-12 
paoldh (old highlight type) 16-10 
paovth (overlay threshhold) 12-12, 13-11, 15-3 
papshi/papslo (level control) 12-12, 13-2, 15-11, 15-14 
pardhi (read highlighting) 12-12, 13-14, 13-16 
paset (set of fields to process) 15-11 
passec (screen save element count) 18-19 
patrid (terminal ID) 12-12, 18-14, 25-3 
patrkn (field tracking on) 12-12, 13-4, 13-10, 13-13, 18-5 
paval (valid characters array) 6-4 
pavdu (vdu structure) 21-27 
pavin (valid numeric characters array) 6-2 
paxasn (XA substrings number) 17-12 
paxasp (XA substring pointers) 17-12 
paxtra (extra upper-case conversion pairs) 6-2 
prelx/prely (relative position) 17-4, 17-8 
pvtbl (validation pointer table) 7-6, 19-1 
Graphics functions 12-8 
Graphics library 11-2 
Interfacing 20-4 
Graphics mode 1-4, 4-6, 22-6 


Index Page 9 
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HB extended attribute 6-11, 13-16 
Header files 12-1 

PANEL.H 12-1 

PCS.H 12-1 

PFCB.H 12-2, 13-3 

PFI.H 12-2 

PFLIST.H 12-2 

PKB.H 12-2 

PNL3.H 12-2, 15-2 

PNLS.H 12-2, 15-11 

PNLC.H 12-2 

PNLI.H 12-3, 20-2 

PPCB.H 12-3 

PSC.H 12-3 

PUPC.H 12-3, 15-1 

PVAL.H 12-3 
Heap usage 25-6 
Help box 5-5, 6-11, 13-16, 19-3 
Help message 5-5, 6-6, 13-16, 19-3 
High bit, set in string literals 10-3 
Highlight modifier 8-8, 21-6 
Highlight type 8-8 

for Amiga 23-5 

for messages 14-2 

for panelp editor 21-14 
Highlight type for read (pardhi) 12-12 
Highlighted bar 14-6, 14-9, 15-15 
HM extended attribute 6-6, 13-16 
Home key 5-5 
Horizontal scroll 13-16 
HS extended attribute 6-11, 23-8 


I 
‘TY’ libraries 22-5 
IBM 6150 RT PC 12-6 
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IBM Personal Computer 1-4 
ANSI driver 22-2 
Configuration 22-1 
Memory-mapped output 20-3, 22-4 
ROM BIOS operations 18-9, 18-17, 18-19, 22-3 
Screen attributes 21-23 
‘tailor’ features 21-21 
IBMBIOS define 12-7 
Include files, angle brackets 10-3 
Include files, nesting 10-3 
Include files, quotes 10-4 
Initialising a field 8-7 
Initialising PANEL Plus operations 13-4 
Insert character 5-4 
Insert line 5-4 
Insert mode 5-2, 12-6, 19-3 
Installation 
Executable files 3-2 
Header files 3-2 
Libraries 3-2 
Message files 3-2 
Integer attribute 6-2 


K 


KEEPIJ mode switch 13-13, 13-17, 14-9 
‘key’ field attribute (PANEL) 25-2 

Key Validation 19-2 

Keyboard background operations 18-3 
Keyboard function pointer (pakbfp) 12-10 
‘keyboard’ program 3-4, 21-8, 21-26 
Keyboard sequences 21-18 

Keyboard status 12-7 


L 


Id errors 3-2 
LDOBOTH mode switch 13-2 
LDOEXP mode switch 13-3 
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LDOIN mode switch 13-2 

LDONOIN mode switch 13-2 
LERRBRK mode switch 13-2 

Level control (papshi/papslo) 12-12 
Levels 4-1 - 4-2, 8-2, 8-11, 9-2, 13-2, 13-11 
LF1BRK mode switch 13-15, 25-3 
Library source code 1-3, 7-1 

Line validation 4-3, 19-6, 25-3 

Linking programs 11-1 

List mode 13-2 

LNOLEV mode switch 12-12, 13-2 
Loading screen layouts dynamically 13-21 
Long integers 6-3 

Lose field 13-19 

LOWFILE define 12-7 


M 


Makefiles 11-1 
Mandatory field attribute 6-3 
‘Mask’ field 8-7 
Maximum column number (pamcol) 12-11 
Maximum row number (pamrow) 12-11 
Memory allocation for dynamic load 13-22 
Memory-mapped switch (pammap) 12-11 
Menu function 14-6 
Menu functions 
Conversion from PANEL 25-6 
Merging screen layouts 8-16 
Message end point (pamen) 12-11 
Message function 14-2 
Message heading (pamhd) 12-11 
Message line (pamln) 12-11 
Microsoft Windows 20-3 
Mouse 
Selection in pmenu 5-6, 14-7 
Selection on message line 5-6 
Special function key numbers 18-12 
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Mouse button selection 5-1, 8-3, 9-1 
Mouse functions 5-5, 20-3, 20-6 
Mouse location (pamoux/pamouy) 12-11 
Mouse switch (pamous) 12-11 
Moving a field 8-13 
MS-DOS 11-2 
MSG environment variable 3-4 
Multiple PNL file control (pamult) 12-11 
Multiple PNL file dynamic load 13-25 
Multiple PNL files 9-2, 13-21 

Index 9-3 


N 


Naming convention 
Base functions 7-4 
Field primitive functions 7-8 
Validation functions 7-7 
NEWLINE define 12-7 
NF extended attribute 6-2 - 6-3, 6-9 - 6-10, 12-12, 13-8 
Examples 6-10 
Use with FORTRAN 6-11 
NOGRAPH define 12-8 
NOKS define 12-7 
Non-standard panel control block 13-22 
nonul field attribute 13-22 
Null byte at end of field line 13-22 
Null pointers 12-9 
Numeric currency array (panumd) 12-12. 
Numeric currency array size (pamaxd) 12-11 
Numeric digit validation 6-4 
Numeric field processing 6-9, 13-8, 13-20 
Numeric field validation 6-5 
Numeric format override 6-10 
Numeric integer array (panuml) 12-12 
Numeric integer array size (pamaxl) 12-11 


eee ane ane SU ere: Senin CT SO een wee ERE pana Ps 


Index Page 13 


O 


‘One byte by one byte’ byte data area 8-10 
open mode 12-9 
Operating system selection 12-5 
Operating systems 
MS-DOS 11-2 
QNX 1-4, 10-3 - 10-4, 24- 
UNIX 1 4, 11-2, 12-7, 24- 
VMS 24-2 
Xenix 11-2, 24-1 
Operation mode 13-2 
Overlapping fields 4-1 
Overlay mode 1-2, 8-11, 13-6, 13-10 - 13-11, 13-13, 
13-18 - 13-19, 18-18 
Overlay threshhold (paovth) 8-11, 12-12, 13-11. 
Overlayed programs 4-5, 10-4 


r 


PAIATT environment variable 3-5, 22-5 
PAIBOR environment variable 3-5, 22-5 
Panel control block 1-3 

Array size 12-8 
Panel control block header file 12-3 
PANEL field function 15-2 
PANEL version 5 8-2, 10-4 
PANEL.VDU 18-14, 21-2, 21-7 
‘panelp’ program 1-3, 3-3, 4-1, 8-1 
PANELP.MSG 6-12 
‘panelpi’ program 3-3, 8-2 
‘panelpt’ program 3-3 
‘paneltc’ program 24-1 
‘pangenc’ program 1-3, 4-5, 8-7, 10-1, 23-8 
PANGENC.MSG 10-1, 10-4 
‘pantest’ program 9-1 
pantest source 9-1 
‘pantesti’ program 9-1 
PANULD define 12-9 


2 
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PANULF define 12-9 
panumd array 6-10 
panuml array 6-10 
PAOMOD define 12-9 
Password fields 6-4 
PATERMIO define 24-2 
PATH 3-2 
Path delimiter character 12-6 
Path name separator 12-6 
PCBFLDS define 12-3, 12-8, 13-22 
‘pcmu’ program (Amiga) 23-4 
‘pd’ program (PANEL) 25-2 
Picture validation 6-4, 6-7 
PLVNV.C module 12-8 
PNL environment variable 3-4, 8-3 
PNL files 4-1, 8-2, 13-21 

Multiple 9-2 

Portability 4-5, 10-4 
‘pnlindx’ program 9-2, 13-25 
PNLMONO environment variable 3-5, 22-4 
Portability 1-3, 20-2 
Porting generated code 10-2 
PPROTO define 12-8 
Pre-processor defines 12-4 
Preparing a field for display 13-7 
printf 6-10 
Processor selection 12-4 
Program function key 5-5 
Program size 25-6 
PV extended attribute 6-7 
PVTBL.C module 19-1 


Q 


QNX 1-4, 10-3 - 10-4 
Query 5-5 
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Range check 6-10 
ranlib 3-2 
Reading a field 13-14 
Reshaping a field 8-13 
Return codes 
Answer function 14-4 
Character validation 19-4 
Conversion to old PANEL code 17-9 
Dynamic load 13-22 
Field display 13-13 
Field read 13-15 
Field validation 19-8 
Free loaded screen layout 13-24 
Key validation 19-2 
Line validation 19-6 
Menu function 14-8, 15-15 
Multiple PNL file lookup 13-26 
Multiple PNL file open 13-25 
PANEL field function 15-8 
Right-justify attribute 6-2 
ROM BIOS functions 12-7 
Royalties 1-3 


S 


Saved field list index (paflx) 12-10 
Screen save operations 18-138 
Sequence numbers 8-8, 8-17 
Special character validation 6-5 
Spoken help message - Amiga 6-11 
sscanf 6-2 
Stack usage 25-6 
Static data 4-4 
stdout 18-7 
String literals 

Compiler limits 4-4 
SWAP(x) macro 12-6 
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System date 12-6, 13-8, 25-2 
System date 6-12 


2 


'Tabulate 5-5 

TAILOR define 12-8 

TAILOR environment variable 3-4 
‘tailor’ program 1-4 - 1-5, 3-1, 3-3, 21-1 
TAILOR.DAT 18-14, 21-2, 21-7 
TAILOR.MSG 21-2 

tcap 1-4 

TERM environment variable 3-4, 18-14 
termcap 24-1 

Terminal ID (patrid) 12-12 

termio 1-4, 3-3 - 3-4, 24-1 

Texas Instruments Professional Computer 21-25 
Toggle list validation 6-5, 13-7 
Topview 20-3 

‘Typing’ mode 8-14 


U 


uchar typedef 12-9 

UCI macro 12-9 

uint define 12-10 

UNIX. 1-4, 3-1, 11-2, 12-7, 18-16, 24-2 
Unshow field 13-18 
Unsigned character 12-9 
Unsigned short integer 12-10 
Upper case attribute 6-2 
USEFLOAT define 12-8 
USEFOP define 12-8 

User attribute 6-3 

Utility programs 9-1 


V 


Validation functions 6-1 
Built-in 6-2 
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Conversion from PANEL 25-5 
Pointer table 19-1 
Validation source 6-1 
Value list validation 6-6 - 6-7 
VAX/VMS 19-1, 24-2 
VDU environment variable 3-4, 18-14 
‘vdugenc’ program 21-27, 25-4 
Vertical scroll 13-16 
in menu field 14-6 
Victor/Sirius Computer 21-26 
VL extended attribute 6-5 - 6-7, 13-7 
VOID define 12-9 


W 


Wang Professional Computer 21-25 
Wipe attribute 6-2 
Word-wrap validation 6-5 


X 


X attribute 6-3, 25-2 
Xenix 3-1, 11-2, 18-10, 24-2 


ZL 
-z switch 8-2, 25-2 
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